Troubleshooting

Each heading below is what you see. Under it is why it happens and what fixes it. For the numbers behind the limits, see Limits and plans.

A client gets a 401 from your server

A private server answers only calls that carry a Sokie token. Without one, the client gets:

This server is private. Connect with an MCP client that signs in to Sokie.

Add the server in a client that signs in to MCP servers, like claude.ai, ChatGPT, Cursor, Claude Code or VS Code, and choose Allow on the Sokie page it opens. See Connect an MCP client. A plain HTTP request, like curl, can't sign in: use sokie call --production instead, or make the server public if its API is public anyway. One refused call before a client signs in is normal; it's how the client learns where to sign in.

If the client did send a token, it gets this instead:

This server refused the runtime token: it is expired, malformed, or for another server.

The client can no longer renew its access: it was disconnected under Settings › Connected clients, it went 90 days unused, or the token came from somewhere else, like sokie dev. Remove the server from the client, add it again, and approve it.

A tool answers with a link to add your key

The server's API takes each caller's own key, and you haven't saved yours. A client that can open links shows Sokie's page; one that can't shows the address in the tool's answer:

Add your own key for Petstore in Sokie to use this tool. Open this page, then run the tool again: https://sokie.sh/connect/majestic-lobster-123 Reconnecting or signing in to Sokie again will not fix this; the credential has to be provided at that page.

Open the page, paste your key, choose Save key, and run the call again. If your API later refuses the key, the next call sends you back to the same page for a new one. See When a caller brings their own key.

A tool says your API didn't answer within 30 seconds

A server waits 30 seconds for your API on each call, then gives up, so the agent isn't left waiting with it; clients may try the call again. If it keeps happening, check that the API is up, and whether the call asks for more than it can answer quickly: a tool description that steers agents to a filter or a smaller page helps. A server deployed before this limit waits as long as the client does; redeploy it from its Deploys tab to get it.

sokie deploy stops with errors

$ sokie deploy
✗ tools/getPet.md  The spec has no operation GET /pets/{id}.  [unknown-operation]
✗ 1 error; run `sokie check`.

The checks found something that stops a build, so nothing was uploaded. Each line names a file and, in brackets, a rule; Checks says what each rule means. Fix them, run sokie check until it prints OK, and deploy again. Lines that start with ! are warnings, which never stop a deploy.

The spec doesn't say where its API answers

On the New server page:

The spec doesn't say where the API answers. Give its address.

In sokie init and sokie check:

✗ sokie.json  The spec declares no server URL; set upstream.baseUrl.  [missing-base-url]

Sokie sends each call to the server URL the spec names. This spec names none, or only a relative one, or one with a variable that has no default. A GraphQL schema never names its endpoint. On the page, fill in the API's address. In a repository, set it in sokie.json:

{
  "upstream": { "baseUrl": "https://api.example.com/v1" }
}

A deploy fails with MISSING_SECRETS

✗ Set TASKS_WORKSPACE_ID before deploying (`sokie secrets set`).

The server uses a secret that has no value on Sokie yet. Set it with sokie secrets set TASKS_WORKSPACE_ID, or on the server's Secrets tab, and deploy again. If a secret is removed from a running server, the tools that need it answer this until it's set again:

The secret TASKS_WORKSPACE_ID is not set for this environment. Its owner sets it with `sokie secrets set TASKS_WORKSPACE_ID`.

See Add secrets.

sokie says you're not signed in

The CLI says one of these:

✗ Not signed in to https://sokie.sh. Run `sokie login`.
✗ Your sign-in to https://sokie.sh has ended. Run `sokie login`.

Run sokie login. A CLI sign-in ends 30 days after you approve it, or after 7 days without use, unless you changed those under Settings › CLI sign-ins. If the address isn't the Sokie you use, SOKIE_SITE or --site is pointing the CLI somewhere else.

sokie says this directory isn't linked to a server

✗ This repository isn't linked to a server on https://sokie.sh. Run `sokie deploy --create`, or `--server <slug>` for one you have.

Other commands say No server is linked here for https://sokie.sh. Pass --server <slug>, or deploy first. The link lives in .sokie/servers.json, which git ignores, and it's kept per site. So a fresh clone has none, and neither does another site you point the CLI at. Pass --server <slug> to name the server. sokie deploy --server <slug> and sokie edit <slug> also link the folder for next time. Use --create only for a new server: it makes another one, at a new address.

sokie dev won't start, or sokie call can't find it

• No sokie.json in /Users/you/code. Run sokie dev in a server's repository. Go to the folder that holds sokie.json; in a monorepo, that's the server's own folder.
• .sokie/dev.env is not gitignored, so its secrets could be committed. Add .sokie/ to .gitignore and run sokie dev again. Do as it says.
• ! SOKIE_CALLER_KEY is not set in .sokie/dev.env; tools that call the upstream need it. The server uses each caller's own key, and locally that's yours. Add SOKIE_CALLER_KEY=<your key> to .sokie/dev.env; the next call reads it, with no restart. Until then, tools that need the key answer No key for this API in sokie dev. Set SOKIE_CALLER_KEY in .sokie/dev.env, then call the tool again. An API that uses OAuth takes SOKIE_OAUTH_TOKEN the same way.
• sokie dev isn't running for this checkout. Start it with: sokie dev Without --production or --preview <n>, sokie call calls the sokie dev running for this folder. Start it in another terminal, or call a deploy instead.

"No MCP server lives at" your address

No MCP server lives at majestic-lobster-123.sokie.cloud.

Nothing is deployed at that address. Check the slug for a typo, and copy the address from sokie deploy's Live: line or the top of the server's page. A server answers only once its first deploy is live, a deleted server's address stops answering, and a preview's address goes when its pull request closes. Previews live at pr-<number>--<slug>.sokie.cloud.

You can't sign in to Sokie

• You’re on the waitlist. Sokie is letting people in a few at a time. It made no account, and emailed you to say so. When there's room, sign in the same way.
• That account’s email address isn’t verified. Verify it with GitHub or Google, then sign in again. Sokie only lets in an address your provider has verified.
• That account can’t sign in here. Try another account, or ask whoever runs this Sokie for access.
• That address has been sent a few links already. Use the newest one, or try again in an hour. An address gets 5 sign-in links an hour.
• This link has expired. A link works once, for 10 minutes. Ask for a new one and use the newest email.

The New server page won't read a spec's URL

• Sokie fetches specs over https only.
• That address is inside a network. Sokie reads specs only from public addresses, never localhost or a private network. Paste or drop the file instead, or run sokie init with it on your machine.
• The URL answered 401. The spec needs credentials to read. Tick It needs a header to read and give the header. It's sent once, for that fetch, and never kept.
• The URL didn't answer in 20 seconds. or The URL redirects more than 3 times. Download the spec, and paste or drop it.
• The spec is over 14 MiB, the most a deploy reads. No spec that size deploys, from a URL or a file. A YAML or GraphQL spec stops at 2 MiB; a YAML one deploys up to 14 MiB once it's JSON. See Limits and plans.
• You've read a lot of specs today. Make a server from one, or try again tomorrow. You can hold 20 specs read and not made into servers, each for a day.

Pushes to GitHub don't deploy

• sokie link says The Sokie App isn't installed on your-org/petstore. Install it (https://github.com/apps/sokie-app/installations/new), then run sokie link again. Install it on the repository's account, then link again.
• The Deploys tab says Sokie can’t see the repository. The App was uninstalled or suspended, or the repository was taken out of its installation. Choose Give the App access. Pushes made meanwhile aren't deployed on their own, so push again.
• Last push says not deployed: over the plan's server limit. See past your plan's server limit.
• Only pushes to the default branch deploy, and pull requests from forks are checked but never previewed.

The From GitHub list on the Deploys tab says what each push did. See Deploy from a GitHub repository.

Tool calls say this month's calls are used up

On Hobby, every tool call in the workspace answers:

This workspace has used this month's free tool calls on Sokie. Its owner can turn on pay as you go in Billing to keep going at once; otherwise tool calls resume on 2026-11-01 (UTC).

At a spending cap, it answers:

This workspace reached the monthly spending cap its owner set in Sokie Billing. Tool calls resume on 2026-11-01 (UTC), or as soon as the owner raises the cap.

Clients can still connect and list tools, and the app and CLI say Tool calls are stopped. On Billing, Turn on pay as you go, or raise the cap; either lifts the stop straight away. Otherwise calls resume at 00:00 UTC on the 1st.

"This server's rate limit is reached"

This server's rate limit is reached. Try again after 2026-10-21T14:04:00.000Z.

One caller sent this server more than 120 requests in a minute, or 20,000 in a UTC day. Every request to /mcp counts, connecting and listing tools included. Wait until the time it gives; the retry-after header has it in seconds. Other callers aren't affected.

"This server is paused by its owner"

The server was paused, so it turns every call away with a 503, at its address and its previews alike. Choose Resume on the server's Settings tab. A server past your plan's server limit can't resume until the workspace is back within it. See Pause a server.

A deploy is refused as past your plan's server limit

✗ This server is past your plan's server limit, so it takes no deploys. What is live keeps serving. Delete servers or upgrade on the Billing page, then deploy again.

The workspace has more servers than its plan includes, usually after a downgrade. The newest ones past the limit keep serving their live deploy, but take no deploys from the CLI, the app or GitHub, and a paused one can't resume. The Deploys tab says This server takes no deploys on your plan, and a push's Sokie check on GitHub fails as Over the plan's server limit. Delete servers you don't need, or upgrade on Billing, then deploy or push again.

At the limit, sokie deploy --create won't make another server:

✗ Your plan's servers are all in use. Delete one or upgrade on the Billing page to make another.