Troubleshooting
A few things to check when setup, login or an agent connection gets stuck.
Most setup problems come down to a missing provider setting, the wrong public URL, or a backend that isn't running. Here are the checks I would start with.
The repository can't be cloned
Check the repository name on your kit's installation page and the GitHub account you are using. Private repositories need access before cloning works.
The local app opens, but requests fail
Check that the database/backend is still running. Supabase and Postgres need their local services; Convex needs its selected local backend; D1 uses the Worker bindings.
For Supabase, follow local Supabase per agent. Remove fixed service ports and use the current project's env.API_URL and keys from supabase status --output-format json. After changing branches, start the selected project, refresh the web env values and restart the dev server. The web servers still need distinct ports.
For other database kits, check the ports in their local configuration when running more than one kit.
Supabase rejects a flag or env sync fails
Run pnpm --filter database exec supabase --version and confirm the pinned CLI version and [experimental] stack = true. Stack commands use --output-format json; connection values are nested under env. Older sync scripts using --output json need updating, including copying the assigned API URL. The new engine doesn't support the old stop --no-backup cleanup flow; use stop to preserve data.
If native startup fails, check the supported platforms and download requirements. Use Docker on Windows or Intel Macs. A project keeps its first runtime; starting an existing Docker project with --runtime native does not convert it.
A Docker image can't be pulled
Check the image tag in that kit's Compose file. An unavailable optional storage image can prevent an all-services startup command from finishing. Update the tag to one you can pull, or start the database and email services you need while you configure storage separately.
Verification emails don't arrive
Check the sender, domain verification and email provider in the place your auth backend reads from. Supabase Auth uses project SMTP settings. Convex Auth reads deployment variables. Better Auth uses the application's server or Worker configuration.
For local testing, check the local inbox first. See emails with Resend.
Login returns to the wrong page
Check the canonical app URL and auth callback allowlist. An MCP login should return to /mcp/authorize with the original pending request preserved.
If the request expired while you were signing in, restart the connection from your agent. Pending consent requests are short-lived.
The MCP endpoint returns 401
Opening an MCP URL without an agent token should return an authentication challenge. That is expected.
If an approved agent gets 401, check that it is using the correct user/admin endpoint. The original sign-in session may have ended, the connection may be revoked, or the account may have lost access. Sign in and reconnect.
There is no workspace to select
Create or join a workspace in the website first. Your membership also needs permission to view projects. The consent page only offers workspaces the account can use.
The admin connection returns 403
Check the application's admin role. Being a workspace owner doesn't grant application-wide administration. Use the trusted admin setup for that kit.
The agent can't create a project
Only the Convex user MCPs have projects_create in v5. They need explicit user:write consent and current project creation permission. All six Supabase, Neon and D1 MCPs are read-only.
The client never gets to consent
Check that it supports public dynamic client registration and PKCE S256. Confidential clients and client ID metadata documents aren't supported yet.
On Convex, copy the .convex.site MCP address from connection settings. The frontend website address is not its backend MCP address.
The D1 app fails intermittently
Check Worker logs for CPU limits and confirm the production database binding. The Next.js demo needed Workers Paid for its auth workload. A build that contains a placeholder D1 ID needs to be rebuilt with the production environment.