Troubleshooting

First move: tell your coding agent what you expected and what happened. With the Stardeck MCP server connected, it can read deploy errors and logs itself. In the browser, click Fix with Agent on a failed deployment to hand the error to Starcat Developer.

Running your app locallyCopy Anchor Link

The CLI says Not logged inCopy Anchor Link

Run npx @stardeckai/cli login, or set STARDECK_API_KEY in CI.

The CLI can't choose a projectCopy Anchor Link

• Cannot select a project interactively: run npx @stardeckai/cli link --project <app> once, or pass --project. See Link an app to its project.
• stardeck.project.json is not usable: fix the file, run npx @stardeckai/cli@latest, re-run link, or pass --project.

env pull returns 403 or 404Copy Anchor Link

• 403: you need the Admin role in the app's organization, or an Admin API key.
• 404: the project or branch isn't one you can access.

The local app can't reach a serviceCopy Anchor Link

Re-run env pull, then restart npm run dev.

STARDECK_AI_API_KEY is missingCopy Anchor Link

Turn on AI Proxy, pull the environment again and restart. Don't add your own provider key.

Details: Run Your App Locally.

Connecting your agentCopy Anchor Link

Your agent can't see the Stardeck toolsCopy Anchor Link

• Run /mcp (or claude mcp list), pick the server named after your organization (stardeck-<organization>, or stardeck if you added it by hand) and finish the browser sign-in. Then restart the agent.
• "This connector has no tools available" means the connection's role has no agent permissions. On the Agents page, switch to a role with agent:* permissions.

A tool you expected is missingCopy Anchor Link

Most tools sit in a catalog, not in the tool list. Ask the agent to search it (search_stardeck_tools). If nothing turns up, the role or access level doesn't allow it. See How tools are disclosed.

Sign-in ends in an error, or calls say UnauthorizedCopy Anchor Link

You signed in to the wrong organization. In the org picker, pick the organization that owns the app. The role list only shows roles you may assign yourself; ask an admin for others.

The agent says the app isn't foundCopy Anchor Link

The app is in another organization, or the slug is wrong. Ask the agent to list your organization's apps.

Tools return "Access denied", or can't write to a data storeCopy Anchor Link

The per-object check failed: for example, a data store with no grant for the role, or a knowledge folder it can't read. Check the store's Access settings or the folder's permissions. Data-store writes also need a Write or Admin connection and a role with agent:data-store:write.

The connection disappears after a restartCopy Anchor Link

Check the server URL and that the token isn't revoked on the Agents page. Re-run the client's setup command.

Details: Connect Your Agent.

While you're buildingCopy Anchor Link

The preview doesn't show your latest changeCopy Anchor Link

Wait for the sandbox preview to rebuild, then refresh. If it is still stale, ask the agent to restart the preview, or use Restart Dev Server in the logs panel.

The cloud sandbox doesn't have the commit you pushedCopy Anchor Link

Pushing doesn't update the cloud sandbox. Open Git History on the app's branch page and click Load into Sandbox on the commit. See Working alongside the Stardeck agent.

The app says a key, token or setting is missingCopy Anchor Link

Set the environment variable for the environment you're testing. Production secrets aren't copied to the sandbox, and the reverse. See Environments.

Test data shows up in the live appCopy Anchor Link

A new app's sandbox and production use the same database, so whatever you create while testing is live. Give the sandbox its own branch. See Give the sandbox its own data.

Data looks wrong, empty or out of dateCopy Anchor Link

Check which data-store branch the environment you're looking at uses. Ask your agent (getProjectDataStoreEnvironments) or open the Branch routing panel under Settings → Data Stores. A table or column added on one branch isn't on the others until you deploy it there.

The agent went down the wrong pathCopy Anchor Link

Ask it to undo, or use conversation forking to restart from an earlier point.

A feature branch merge says the main agent is busyCopy Anchor Link

Wait for that run and retry. Merges are not queued. Feature branches isolate code, chat and sandbox runtime, not shared sandbox data. Feature branches can create shareable preview deployments, but production publishing stays on the default branch, so merge and verify there first.

A deploy failedCopy Anchor Link

A failed deploy doesn't take the app down. The previous deploy keeps serving until a new one succeeds.

The deployment card shows a plain-language summary. Click it to see the key errors and a Suggested fix. Below it is one button:

• Review & Redeploy when the failure looks temporary, such as a network blip or a download timeout.
• Fix with Agent otherwise. It sends the error and deployment context to Starcat Developer.

Common causes:

• Build or type errors. The most common. Fix with Agent gets the exact error lines.
• Schema missing in production. A table or column added on the sandbox's branch never reached production (or the preview's branch). Check which branch each environment uses. See Environments.
• Destructive schema change. Publishing pauses for you to confirm a dropped table or column in production. Preview deployments don't ask.

Raw logs are in the failed deployment's details.

Read a failed deploy from your own agentCopy Anchor Link

• get_project_deployment_status shows the latest deploy and the one actually serving. They differ when the newest deploy failed or is still running. A failed deploy carries its recorded error and an AI-written failure summary, which can be wrong.
• get_project_deployment_logs reads a deploy's build and deploy logs.
• list_project_deployment_revisions lists past deploys with their commits, so you can see which commit last deployed cleanly.

Fix the cause on a branch and deploy again. See Operate Your App for the permissions these tools need.

A Surface or Module is missingCopy Anchor Link

A Surface is missing or not liveCopy Anchor Link

In Settings → Deployments → Production, Ships on next deploy means it needs a production deploy. Removed at tip means it is gone from the current branch. Click Sync surfaces after committing, then deploy. Dedicated non-root Surface URLs are production-only. See Surfaces.

A Module is missing or its setup failedCopy Anchor Link

In Settings → Modules, open the menu and choose Sync from this branch, or ask the agent. See Modules.

An update tool refuses or doesn't appearCopy Anchor Link

See the error table in Take an update locally.

Still stuck?Copy Anchor Link

Contact support with what you were doing and what failed.