Skip to content

Fix common agent problems ​

Start with three checks:

  1. Run agent-sdk validate --dir ..
  2. Confirm the expected agent and connections in agent-sdk info --dir . --json.
  3. Reproduce the problem once, then read the serve log or the session trace.

Serve or the playground won't work ​

What you seeWhat to do
The playground is blank or lists no agentsStart agent-sdk serve, because the playground gets its agents from the server.
Agent-file edits don't appearOpen the URL that serve --dev prints, and press Enter in its terminal to reload.
Sessions exist but the list is emptyThe list shows only your own sessions, so use the identity that created them.

A turn fails or misbehaves ​

What you seeWhat to do
Reads and greps keep failing with NGHTTP2_FRAME_SIZE_ERRORRun the agent under Node 22.13 or newer, never Bun.
Semantic search has been removed. Use Grep.Delete search from a custom fs, drop SearchQuery and SearchResult, and remove SemanticSearch or semSearch from tools and bot/tools/.
The turn reports a missing API keySet CURSOR_API_KEY, CURSOR_API_KEY_FILE, or CURSOR_SERVICE_ACCOUNT_KEY, or run agent-sdk login.
Login works but the model host rejects the keyPoint CURSOR_API_BASE_URL and CURSOR_BACKEND_URL at the same API host.
The first turn reports [resource_exhausted]The model is usually out of capacity. If a GitHub event started the turn, check for a GitHub 429 rate-limit response first.
Replies quote an ancestor AGENTS.md or unrelated repository rulesSet defineAgent({ local: { cwd } }) so the agent doesn't inherit the parent checkout. /v1/info shows the current local.cwd.
The model lists IDE meta-tools but never calls named MCP toolsSet advertiseTools: true on the local connection.
Server tools, skills, or seed files are missingCheck the discovered project in /v1/info, and follow the warning from validate.
validate and run pass but CI type-checking failsReturn JSON-shaped tool results, such as object literals or type aliases, instead of interface types.

HTTP returns 401, 403, or 409 ​

What you seeWhat to do
401 outside local developmentSend the bearer token, alias token, or channel credential. Default custom routes accept only direct loopback calls.
403 on a stream or follow-upUse the identity that created the session.
A custom route fails through a tunnel or LANProtect the host with --bearer-token or channel auth. Use --allow-anonymous only behind a proxy that authenticates every caller.
409 on a follow-upRefresh the rotating continuationToken. Task sessions don't accept follow-ups.
409 session_busy from call --sessionWait for the turn, omit --session, or mark a read-only tool effect: "read" so it can run alongside the turn.

A hosted deployment fails or looks stale ​

What you seeWhat to do
validate or deploy reports architecture "v2" requires a named secretReplace the literal or getter with a named secret, and set its value with agent-sdk secret set <slug> NAME.
Local changes don't appear after deploydeploy builds the pushed ref, so commit and push your changes, then deploy again.
The deployment never reaches runningRun agent-sdk deployment get <slug>, and fix the error it reports.
A secret or egress change has no effectConfirm the name with secret list, check that the hosting block is on the pushed ref, and redeploy.
A hosted schedule doesn't fireCheck that the deployment is running and that the schedule is in bot/schedules/ on the deployed ref.
The startup log shows requires CURSOR_API_KEYThis is expected. See Startup runs before secrets are available.
A custom route returns 429Wait for the time in Retry-After, then send it again.

GitHub deliveries fail ​

What you seeWhat to do
github forward gets 401 on every deliveryClear the token variables so the forwarder uses your gh login, as in GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward.
Hook already existsStop the stale forwarder. GitHub allows one per repository.
Direct webhooks are rejected outside --devSet the same GITHUB_WEBHOOK_SECRET on the signer and the server.
You can't create a forwarderUse agent-sdk github replay <pr-url>, which needs only pull access.

Slack doesn't respond ​

What you seeWhat to do
Logs say channel idle ... missing credentialsRun agent-sdk slack create --dir <agent>, then check the prefix with agent-sdk slack doctor.
slack create waits for workspace approvalKeep the CLI running and open the Request approval link it prints. After an admin approves, select Retry in the Deployed Agents Add Slack wizard.
The bot ignores ordinary channel postsConfigure engagement.channelPosts, create the app with --channel-posts, and invite it to each allowed channel.

Teams does not respond ​

What you seeWhat to do
channels teams doctor fails the token checkCopy the Microsoft App ID and App Tenant ID from the Azure Bot's Configuration page, create a new client secret, and run agent-sdk channels teams init again.
channels teams doctor fails the endpoint check with teams_not_configuredThe server that serves the URL has no app id or password for this channel. Check the channel's envPrefix and the secrets on that server.
channels teams doctor fails the endpoint check with a 404, or says the URL is not this channel's endpointThe URL has the wrong path. Use the endpoint that dev printed. It ends in /v1/channels/<channel>, plus the channel's path when it sets one.
channels teams doctor fails the bot-tenant checkThe Azure Bot must be Single Tenant, in the tenant that the channel's tenant id variable holds. Create a Single Tenant Azure Bot in your own tenant, then run agent-sdk channels teams init with its ids.
channels teams doctor skips bot-tenant, bot-endpoint, and teams-channelThe Azure CLI is missing or not logged in. Install it and run az login.
channels teams doctor fails bot-tenant, bot-endpoint, and teams-channel with no Azure Bot foundNo Azure Bot in the current subscription has the app id. Check the app id, or select the bot's subscription with az account set.
channels teams doctor fails the bot-endpoint checkSet the endpoint that dev printed on the Azure Bot: Configuration, Messaging endpoint, Apply.
channels teams doctor fails the teams-channel checkOn the Azure Bot, open Channels, select Microsoft Teams, then select Apply.
agent-sdk dev prints warning: Teams tunnel: cloudflared is not installedInstall cloudflared, put it on PATH, and restart dev.
agent-sdk dev --tunnel devtunnel prints devtunnel is not logged inRun devtunnel user login, or devtunnel user login -g for a GitHub account, and restart dev.
agent-sdk dev --tunnel devtunnel says the dev tunnel also publishes another portdevtunnel host publishes every port on the tunnel. Remove the other port with devtunnel port delete <id> -p <port>, or pass another --tunnel-id.
The bot stops answering after you restart devThe cloudflared URL changed. Set the endpoint that dev printed on the Azure Bot again, or start dev with --tunnel devtunnel to keep one URL.
The bot cannot be added to a team or group chatUpload the app package: run agent-sdk channels teams package, then in Teams select Apps, Manage your apps, Upload an app.

See Configure Microsoft Teams for the commands.

MCP authorization fails ​

What you seeWhat to do
must be defineConnection({ url, oauth: true })Add oauth: true to the connection, or fix the filename you passed to mcp oauth.
Local auth works but hosted calls return unauthorizedYour local OAuth tokens don't reach a deployment. Use a cursorAccount: true connection, as described in Host MCP OAuth.
An individual cursorAccount: true connection refuses calls or asks to connectConfirm the turn came from a linked user rather than a schedule, webhook, or service-account API key, and follow Per-user MCP connections.
The model invents mcp_auth instead of calling the serverSet advertiseTools: true for named local tools, or expose a wrapper through ctx.host.mcp.

Schedules or reminders stall ​

What you seeWhat to do
A schedule or reminder never fires under --dev--dev doesn't fire them on its own, so trigger one through its /v1/dev/schedules/<id> or /v1/dev/reminders/<id> route.
A reminder is disarmed with handler_lost_on_restartRecreate handler-form reminders after a restart, or use a prompt-form reminder.
One schedule fires on several self-hosted processesPass --no-schedules to every serving process but one.

Read the session trace ​

bash
agent-sdk session list --prod --slug <slug>
agent-sdk session get <sessionId> --prod --slug <slug> --view events
agent-sdk session get --file <trace-path>

Find a hosted session with session list, then print its events with --view events. For a local run, pass the trace path from agent-sdk run to --file. Pair each actions.requested event with its action.result to find the call that failed.