Troubleshooting

Most problems fall into one of the cases below. Sinatra posts what it's doing back on the ticket (a rolling GitHub comment or Linear activity) or in the Slack thread, so that thread is the first place to look. For a task started from the CLI, MCP or API, look at its conversation: sinatra show <task-id>, or the task's page in the dashboard.

The agent didn't pick up my ticket

On GitHub, Sinatra normally acknowledges accepted work with 👀. A missing reaction can mean a trigger was rejected, acknowledgement failed, or processing has not started; it does not prove the webhook never arrived. On Linear, look for the agent session's progress or refusal message.

On Linear:

• The issue must be assigned to Sinatra, or a comment must @-mention it.
• Your Linear workspace must be connected. Check Connect Linear in workspace settings — it's optional, and nothing fires until it's connected.
• The person delegating must be a Sinatra workspace member with a linked Linear identity for that organization. Installing the integration alone does not link every teammate. See Linear setup. If their Linear account isn't linked, Sinatra says so in the issue's agent session and emails the address on that Linear account with a link to Settings. Once it's linked, mention Sinatra in a comment on the issue to start; assigning it again does nothing while the issue is still delegated to Sinatra.

On GitHub:

• Add the Sinatra label to the issue — sinatraai on the hosted app. The name must match exactly; a differently named label is ignored. The trigger compares the name, not who created the label.
• A comment alone will not start a run on GitHub. Comments only continue a task the label already started.
• The person who adds the label or comments must be a member of the Sinatra workspace, and their Sinatra account must use that GitHub account, by signing in with it or linking it (Link GitHub in Settings, for an account made by email). Otherwise a label gets a reply: someone without a Sinatra account is told only invited members can run tasks, and someone with one is told the owners have been sent an access request. A comment on the issue gets no reply, though a commenter with a Sinatra account still sends the owners an access request.
• The GitHub App must have access to the repo, its installation must be active, and the repo must be enabled in Sinatra's Repos tab. See GitHub App.

Linear authorization required

auth_required means Sinatra could not authorize the run against Linear: the delegating person lacks a linked Linear identity or workspace membership, or the workspace's Linear installation is missing or needs reconnecting. The delegator should use Link Linear identity in the affected workspace's Settings and authorize the same Linear organization as the workspace install; an owner or admin can reconnect the installation with Connect Linear. Then delegate or mention Sinatra again.

On a GitHub issue, auth_required means the person who added the label or commented isn't a member of the Sinatra workspace. An owner can invite them or approve their access request; then they can try again.

No pull request appeared

Open the ticket, or the conversation of a task started from the CLI, MCP or API, and check the task's state in the dashboard (see What the states mean). A task doesn't have to produce a PR: it can answer a question or propose a plan instead. The usual reasons:

• It needs your input. The agent may ask a question or propose an approach instead of changing code. Reply to clarify or request implementation. Planning and brainstorming do not have separate approval gates.
• It's queued. Your plan's tasks-at-a-time limit is reached, so the task starts on its own when another finishes. Sinatra posts its position on the ticket: "Queued (position 2). I'll start as soon as a running task finishes."
• The queue was full. Sinatra didn't start the request and said so on the ticket (see below).
• Billing paused it. The raw status is payment_required and Sinatra posts why (see below).
• The run failed. The task shows Needs your input, with an explanation on the ticket.
• Authorization is missing. auth_required needs the fix above.

Sinatra's post-implementation test hook does not itself block PR readiness — see below. The agent can still fail or stop before creating a PR, so inspect the run's reported outcome.

The agent has stopped producing output

After ten minutes without new complete output, Sinatra warns in the task conversation. A long-running command may still be working: the warning does not stop the agent, and monitoring continues.

We send one warning per quiet stretch. New output resets the warning, so a later ten-minute quiet stretch can warn again. The existing maximum runtime, confirmed failure checks and stop controls still apply. Check the conversation for the final result before treating silence as failure.

Claude subscription limits

Sinatra reads Claude Code's modern reset-time messages, such as resets 3pm (UTC), and structural retry-after values. The old usage limit reached|<epoch> text format no longer supplies a reset time; when the reset is unknown, Sinatra does not guess.

The PR opened but the tests are red

The agent usually opens the draft PR during implementation, before Sinatra runs hooks.test_command. Sinatra makes up to two agent attempts to fix a failing test command. If it still fails, the failure is reported and the PR can still become ready for review. Check the ticket's output and enforce any required passing tests through your repository's merge rules.

The queue is full

Your plan sets how many tasks run at once and how many more can be queued. When both are full, Sinatra doesn't start a new request. It says so on the ticket instead, and the request isn't queued:

Your workspace's queue is full (Pro plan: 3 tasks at a time, plus 10 queued), so I didn't start this one. Try again once a running task finishes.

On Free, the message ends with ", or upgrade for more room:" and a link to workspace settings. To get it going:

• Send it again once a task finishes. A queued request starts on its own; a refused one doesn't, so reply or mention Sinatra again when there's room.
• Stop work you no longer need. Stopping a queued task takes it out of the queue.
• Move to a bigger plan. On Free, the owner picks a plan from the settings link in the message. On a paid plan, the owner changes plans from Settings → Billing; upgrades apply immediately.

A failed CI check gets the same treatment: if the queue is full, Sinatra posts on the PR that CI failed but it didn't start a fix. Reply on the PR to ask for it. See How the queue works.

A Free request stopped after 60 minutes

On Free, each request runs for up to 60 minutes. If it needs longer, Sinatra stops, keeps the changes, and picks up when you reply. On a PR, mention Sinatra in your comment so it sees the reply.

Payment required

The raw status moves to payment_required, the task shows Needs your input, and Sinatra posts a message when billing pauses a run, ending with a link to the settings section that fixes it:

• Payment past due. A past-due subscription keeps working for a 7-day grace period, then new work pauses until the card is fixed. The owner updates it from Settings → Billing. An ended subscription is different: the workspace returns to Free (1 task at a time, plus 1 queued) rather than pausing.

After fixing a block, reply or send a new trigger if the task has not resumed. See Billing for subscription rules.

If the block says own_credentials_required, connect a personal model subscription in Settings or ask an owner/admin to add a workspace Anthropic or OpenRouter API key. Every account, including existing and paid accounts, requires its own credentials. A teammate's personal connection does not cover your tasks.

The PR is stuck as a draft

PRs open as drafts on purpose. Sinatra attempts self-review before marking them ready. Eligible feedback, stopping the run, or cancellation can interrupt review and leave the draft in place. Check the ticket feed and the sinatra / review check if available. A missing check can mean the installation has not granted Checks write access; a ready PR does not prove review or tests passed.

CI keeps failing and the agent stopped

When a GitHub check suite fails on Sinatra's PR, Sinatra runs a fix as its own turn, after any work people asked for, and explains on the PR. It stops after ci.max_rework fixes in a row (two by default) with no message from a person, and says so on the PR. Fix the branch yourself or leave an actionable PR comment that mentions Sinatra, such as @sinatraai fix the failing lint check; a person's message resets the count. A new config value is read on a later turn; editing the file alone does not wake a paused task.

I want it to start over, or stop it

• Start over from scratch. Send the literal command restart to request a destructive restart: Sinatra drops the sandbox, deletes its branch, closes the existing PR even if it is ready for review, and begins again. Other requests continue the conversation. See Steering a run.
• Stop it. On GitHub, remove the Sinatra label or close the issue; reopening a still-labeled issue triggers a resume attempt. On Linear, Stop interrupts active work and preserves the task for follow-ups; moving the issue to a terminal state cancels active work. If you mark the issue Done while its PR is open, Sinatra replies "Issue marked Done. Reply here if you need anything else." From your terminal, sinatra stop <task-id> stops the current turn and keeps the task for follow-ups; the stop_task MCP tool and POST .../stop do the same. Any workspace member can stop any task this way, wherever it started. Slack has no stop control, so stop a Slack task one of these ways or with Stop in the Running and queued list on the dashboard's overview. In a Slack thread, mention Sinatra with only restart to start over.

A Codex or xAI token refresh timed out

Token refresh requests have one ten-second network budget, including response-body reading. A timeout is a transient failure, not proof that the provider revoked your connection. This budget does not cover encryption or database persistence. Existing refresh serialization remains in place.

The agent ran the wrong model

• A personal override may be in effect. Check Repos → repository for the member who triggered the iteration. See per-user overrides.
• A workspace default may be in effect when the repository has no explicit engine or model. Check Settings → Workspace agent default; an owner can change it or reset to automatic.
• No engine, model or workspace default set? Sinatra picks a default from your available personal connections and shared keys. Setting only engine disables this selection. See Models.
• A teammate connected a subscription? Personal connections cover that member's tasks, not everyone in the workspace. Connect your own subscription or ask an owner/admin about a shared API key.

My .sinatrarc.json isn't taking effect

• It must be named .sinatrarc.json, live at the root of the target repo, and be valid JSON, with no comments or trailing commas. Commit it to the default branch. Existing PR checkouts read the configuration at their verified head commit, so commit the rename on any task branches you still use. The extensionless .sinatrarc filename is no longer read.
• Unknown top-level keys are ignored with a warning, not an error. Check supported sections against the .sinatrarc.json reference. The retired planning and brainstorm blocks are ignored with warnings.
• The agent model must be compatible with the chosen engine. claude-code uses bare names like opus-5-5; oh-my-pi uses its catalog's full slugs. See Models.
• agent.model_provider was removed and is ignored — the provider is derived from the engine and model.
• hooks.before_run, hooks.after_run, agent.timeout_minutes, and agent.max_turns are accepted but have no runtime effect. Describe setup in your README or AGENTS.md for the agent to follow, and use hooks.test_command for verification. sandbox.setup_commands.post_clone, sandbox.clone_strategy, and sandbox.sync_with_base also have no effect today, because the agent prepares its own checkout.

A repository secret is missing or rejected

Check Repos → repository → Secrets. A legacy secret without approved hosts blocks proxied sandbox creation and remains encrypted for repair. Ask a workspace owner or admin to add exact hostnames or supported wildcard patterns, then send the placeholder in a request header to an approved host. It is not a raw local signing key. See Repository secrets.

Signing in

The sign-in email didn't arrive

Check your spam folder for mail from noreply@sinatra.dev. A link works once and expires after 15 minutes, and one address can ask for three links every 15 minutes. An address that belongs to an account made with GitHub gets no link: continue with GitHub instead. A new address without an invitation also has to pass a Cloudflare security check on the sign-in page. If an ad or content blocker stops it loading, the page says so and no sign-up link is sent: allow challenges.cloudflare.com, reload, and try again.

That GitHub account already belongs to another Sinatra account

Sinatra won't link a GitHub account that another Sinatra account already has, usually one you made by signing in with GitHub, and it never merges accounts. Sign in with GitHub to use that account, or link a different GitHub account. If both accounts have the same email verified, Sinatra can't match it to a Linear or Slack identity automatically, so link those from Settings.

The CLI, MCP server or API isn't working

A request was refused

The API Reference lists every error each endpoint can return. The common ones:

• 401 invalid_token. The token is mistyped, expired or revoked. Tokens are shown once and can't be recovered: create a new one on the dashboard's CLI & API page, then update your script or your MCP client's Authorization header, or run sinatra login --token again (CLI 0.2.0 or newer; on 0.1, plain sinatra login asks for the token). If the CLI says your sign-in has ended, it expired or was disconnected: run sinatra login to sign in again.
• 409 github_not_connected. The workspace has no GitHub connected, or its GitHub App installation is suspended, so Sinatra has no repository to work in. A workspace owner or admin connects GitHub from the link in reason, which opens Settings → Integrations. A suspended installation is lifted on GitHub; then the link opens its page there. Start the task again afterwards. A task that runs after GitHub is disconnected says so in its conversation.
• 409 payment_required. Billing would stop the task, so Sinatra didn't make it: connect your own model subscription or add a workspace API key (refusal: "own_credentials_required"), or update the card in billing ("subscription_inactive"). The dashboard's Start work box refuses the same way.
• 409 capacity_full. The workspace's queue is full: your plan's running and queued places are taken, by tasks from any source. The response's reason is the same message the dashboard shows, with the upgrade link on Free. Wait for a running task to finish, stop one with sinatra stop <task-id>, or upgrade. A task Sinatra created but couldn't start (a 503 on start) holds its place for 15 minutes; start it with sinatra reply <task-id> "go" instead of starting a new one.
• 429 with a Retry-After header. You're over the request rate limit for that endpoint. Wait the number of seconds in Retry-After, then retry. All MCP calls share one budget of 120 a minute, so poll get_messages less often.
• 404 not_found. No such task, or the token's account isn't a member of that workspace. Run sinatra whoami to see your workspaces.

An MCP client can't sign in

Claude Code, Cursor, ChatGPT and claude.ai (and Claude Desktop, which shares claude.ai's connectors) sign in to Sinatra over OAuth. Follow the setup for your client, then approve the app on the page Sinatra opens in your browser. A request that has expired or was already used can't be approved: start connecting again from the app.

We haven't tested sign-in with other MCP clients. If one can't sign in, connect it with a personal access token in an Authorization: Bearer header, or use the CLI.

To cut off an app, open the dashboard's CLI & API page and click Disconnect next to it under Connected apps. Its next call is refused, and it has to sign in again to reconnect. Removing the connector in claude.ai, or deleting the plugin in ChatGPT, doesn't revoke access on its own: only Disconnect on Sinatra's page does. An app also asks you to sign in again after 90 days, or after 30 days without connecting.

sinatra exited with code 3

The task was still working when the CLI stopped waiting (after 30 minutes, or your --timeout), or Sinatra hadn't picked up your reply yet. The task keeps going either way. Run sinatra show <task-id> later to read the result. Exit code 2 means the task failed, was cancelled, or is paused on access or billing. See Exit codes.

Slack isn't working

Sinatra didn't respond to my mention

• No 👀 reaction. Sinatra only sees mentions in channels it has been invited to, so invite it to the channel and mention it again. Direct messages aren't supported. Also check that Slack shows as connected on the workspace's Settings page.
• A private message from Sinatra. It tells you what to fix: link your Slack account with Sign in with Slack in Settings, wait for an owner to approve the access request it sent for you, or ask an owner or admin to allow Slack Connect channels.
• A reply in the thread about billing or model access. Fix it as for any task; see Payment required.
• The reaction appeared, then went away with no reply. The 👀 comes off when a turn ends or when Sinatra couldn't hand the request off. Open the task in the dashboard to see where it stopped; its source link goes back to the thread. If there's no task, mention Sinatra again.

Sinatra didn't answer my reply

A reply without a mention only continues the task when Sinatra judges it's meant for it, and it stays quiet when unsure. Mention Sinatra in the reply to be certain.

I can't connect Slack

Only owners and admins can connect Slack; other members see a note asking them to ask one. A Slack workspace can be connected to one Sinatra workspace at a time; if it's already connected elsewhere and you aren't a member there, Sinatra sends an access request to that workspace's owners instead. See Slack.

Sinatra didn't merge my PR

Sinatra does not automatically merge PRs. Review the results and merge through your repository's normal process.