Troubleshooting | StateWeave Docs
Tasks and runs
Troubleshooting
The messages you are most likely to meet, what they mean, and what to do. sw prints the workspace's message after sw: and exits with 1; in Python it is the text of stateweave.StateWeaveError , whose status is the HTTP status.
Connecting
sw: cannot reach https://…
Nothing answered at the address the message names. It should be your workspace's address, such as https://acme.app.stateweave.net , with no path. Set it with sw login --url or STATEWEAVE_URL . With no address set at all, sw tries http://127.0.0.1:8700 , which is not your workspace. A proxy or firewall between you and the workspace can also cause it. If the address is right, the workspace may be restarting: try again in a minute. sw worker keeps trying by itself.
Tunnel connection failed: 403 means a proxy refused the connection. In a coding agent this is usually its own sandbox: Claude Code's lets a command reach only the hosts listed under sandbox.network.allowedDomains . sw setup adds *.app.stateweave.net to ~/.claude/settings.json ; start a new session afterwards.
sw: the answer from https://… was cut off after N bytes
The connection closed before the whole answer arrived: something between you and the workspace, usually a proxy, closed it early. sw sends a cut-off read again by itself, three times, so this means it kept happening. Older versions of sw (0.6.1 and earlier) met this inside Claude Code's sandbox, with IncompleteRead in a traceback: pip install -U stateweave-sdk .
sw: no API key
Neither sw login nor STATEWEAVE_API_KEY gave a key. Run sw login , or make a key in your workspace and set the variable.
did not accept that key / HTTP 401: invalid_api_key
The key was revoked, mistyped, or made in another workspace. Keys are per workspace. Make a new one in your workspace: click the key icon at the bottom of the left rail ( Connect your agent ), then Create key . Then run sw login again. If STATEWEAVE_API_KEY is set in your shell, it wins over what sw login kept: unset it or update it.
A key also stops working when the person who made it leaves the workspace or is removed from it ( Work with teammates ): whoever uses it now makes a key of their own.
HTTP 429: too many requests with this key: slow down
Requests with one key are rate limited. The SDK waits and retries these by itself, three times; a script that still hits the limit is polling too fast.
Sandboxes
HTTP 409: the sandbox is in test mode: start a twin run of it, or switch it to edit mode
You connected to a sandbox in test mode. To change its data, switch it to edit mode first: sw sandbox mode p-… edit . To only look at its apps or try your agent, open a twin run instead: sw run p-… -- COMMAND or stateweave.Client().open_twins("p-…") . See Twin runs .
HTTP 409: actions change the sandbox: switch it to edit mode first
StateWeave's actions, like connecting, work only in edit mode. Switch the sandbox to edit mode, act, then switch it back to test mode to keep a version.
My runs don't see what I added
Runs, twin runs and tests start from the sandbox's latest version, not from what edit mode holds now. Switch the sandbox to test mode ( sw sandbox mode p-… test ) to keep your changes as the next version. sw sandbox changes p-… lists what is not in a version yet.
HTTP 409: runs of this sandbox's tests are going: finish or cancel them first
Switching a sandbox's mode is refused while runs of it are going (twin runs too), or while it re-checks or rewrites its tests: they read the data as it is. Wait for them, or cancel the runs ( sw cancel r-… ), then switch.
HTTP 409: data can only be generated into a blank sandbox
A made-up company can be generated only into a sandbox that is still blank: no version, nothing generated, no change since it was made. Make a new sandbox to generate one. See Fill a sandbox .
Importing a task
The task cannot be read
sw task import lists every problem it found (HTTP 400, with problems ), and nothing is kept. Some you may meet:
| Problem | What to do |
|---|---|
| tests/: a task needs tests/checks.json or tests/verify.py (or both): how it is judged | Add checks, code, or both. |
| task.toml: stateweave_version 1: runs start from the sandbox's latest version (2); leave it out or write 2 | The sandbox has a newer version. Leave the key out. |
| task.toml: stateweave_sandbox is 'p-…', but it is being added to p-… | The sandbox given on the command line differs from task.toml 's. Use one. |
| tests/checks.json: checks[0].state: a check cannot look at the twins' own records; ask the app's API with a request check instead | A task is judged only through the apps' public APIs, the answer and the agent's requests. Use a request check. |
| task.toml: stateweave_pinned_faults[0]: slack chat.postMessage: 'drop' cannot happen there | That kind cannot happen at that endpoint; the message lists the kinds that can. fault_targets() lists every endpoint's. |
| task.toml: stateweave_faults and stateweave_random_faults: faults are injected one way at most | Keep one of the keys. |
Without a sandbox at all, sw says which sandbox? : pass --sandbox p-… or write stateweave_sandbox under [metadata] in task.toml . See Tasks .
tests/verify.py: this hosted studio does not run uploaded code yet
A hosted workspace takes uploaded checks but not uploaded code yet: it refuses a task with tests/verify.py or solution/solve.py . Judge the task with tests/checks.json alone and leave the code out. A task with checks only is proven by doing nothing failing.
Not kept: fix what failed and import it again
The task was read but not proven. sw prints each proof with ✓ or ✗ , and what a failed one found:
| Failed proof | Meaning |
|---|---|
| Doing nothing fails | The checks pass on the sandbox as it is, before any agent works, or they could not run. Passing checks don't test the change the task asks for, or the data already holds the result. |
| The answer format gives no answer away | stateweave_answer_format shows values the checks look for. The agent sees the format, so write it with placeholder values. |
Use sw task import PATH --check to prove a task without keeping it, until every proof passes. See Upload a task .
HTTP 429: … tests a day is this studio's limit
A hosted workspace limits how many tests are added a day. Try again the next day (UTC).
HTTP 410: the studio does not write tasks
Tests are only uploaded now. sw task new , the Python write_tests() , suggest_tests() and job() , and the MCP tools write_tests , suggest_tests and get_test_job are gone, and POST /api/v1/sandboxes/{id}/tests answers 410. Write the task as a folder in Harbor's layout and upload it with sw task import PATH . See Tasks and Upload a task .
Starting runs
HTTP 404: no test t-…
The id is wrong, or the test was deleted. sw task ls lists the tests your key can run.
t-… names a test in several projects: say which
A test id can be in more than one sandbox (the API calls sandboxes projects). Pass the sandbox too: sw run t-… --env p-… , or environment= in Python.
HTTP 409: t-… needs a re-check
A new version of the sandbox changed one of the test's apps, for example the sandbox's Slack data changed (version 2) . What the test checks may have changed with it, so it does not run until it is proven again on the new data. Run sw task recheck p-… , which prints the tests it re-checks, and wait for it to finish. A test that passes runs again. One that fails stays marked, with the checks that failed.
HTTP 429: 8 runs are going already: finish or cancel one first
Your workspace runs a limited number of runs at once. Finish or cancel one first. Runs left without finish() hold their place until they time out, so use the Python with block or give runs up with sw cancel .
HTTP 429: 3 twin runs of this key are going already: stop one first
One key keeps at most 3 twin runs going at once. Stop one you are done with ( twins.stop() in Python, or sw cancel r-… ); otherwise each ends after its time, an hour by default.
HTTP 402: This workspace has used its 5 sandbox hours for this period
The workspace's plan has no sandbox hours left until the date the message gives: no sandbox starts, no sleeping app wakes (its address answers 402 with "error": "plan_limit" ), and no run starts. Work already going goes on. On Free, apply for Basic on the Pricing page, or wait for the 1st; on Basic, email support@stateweave.net to raise the cap. The same answer, with "kind": "sandbox" or "generated" , means the month's new sandboxes or generated ones are used up: deleting one does not give it back. See Pricing .
sw: could not start …
The command after -- doesn't exist or isn't executable. Nothing was started. Give the interpreter explicitly: -- python my_agent.py , -- sh run.sh .
Grading
An answer task fails with no answer
Your agent handed in no answer, so the task's answer checks fail. With sw run , the agent must write its answer to the file STATEWEAVE_ANSWER_FILE names before it exits. JSON there is handed in as its value, and anything else as a string. Check that the file is written to that exact path, in the shape of STATEWEAVE_ANSWER_FORMAT . The run's reasons show each check's result.
HTTP 409: the run has ended
The run timed out or was cancelled (on its page, or by Ctrl-C) before it was finished. In Python this is stateweave.RunEnded , and e.run["status"] says how it ended. A run has 30 minutes by default: raise the limit with --timeout if your agent needs longer.
HTTP 409: a twin run is not graded: stop it (cancel) when you are done
A twin run has no test, so there is nothing to grade. Judge it yourself with its changes or a task's checks, then stop it: twins.stop() in Python. For a graded run, start a run of a test.
The run's status is error
The test's own judging failed, not your agent: the run is not counted against it. The run's page shows why. If that doesn't help, tell us at support@stateweave.net with the run's link.
The run's status is interrupted
The workspace stopped while the run was going, so it was not graded. Start the run again.
Your agent's calls
The agent crashes reading an answer inside Claude Code's sandbox
Run inside Claude Code's sandbox, an agent built on Python's urllib, or on slack_sdk, which uses it, can fail with IncompleteRead or JSON that stops short, on any answer over a few KB. urllib asks the server to close the connection after each answer ( Connection: close ), and the sandbox's proxy cuts off the end of the answer when the server does. The same agent works outside the sandbox. sw run prints a note when your agent fails inside a sandbox. Run the command outside it: in your own terminal, or allow it when Claude Code asks to run it unsandboxed.
A Google client calls the real Google
Google's Python library ships its own copy of each API's discovery document. Pass the app's document and turn the shipped one off: discoveryServiceUrl=…["endpoints"]["discovery"] and static_discovery=False . See Gmail .
slack_sdk calls slack.com
Pass base_url=run.apps["slack"]["endpoints"]["web_api"] to WebClient . The trailing /api/ is part of it. From the variables, it is $STATEWEAVE_SLACK_URL/api/ .
ShopifyAPI calls a real Shopify store
Python's ShopifyAPI turns any shop name into <name>.myshopify.com . Set shopify.Session.myshopify_domain to the app's domain first. See Client libraries .
Octokit uploads a release asset to uploads.github.com
Octokit's repos.uploadReleaseAsset sends the file to uploads.github.com unless you pass the release's upload_url as url . See Client libraries .
A Shopify call answers 404 with x-twin-not-implemented
That's the REST Admin API, which StateWeave doesn't serve. Use the GraphQL Admin API ( admin_graphql ) instead.
A path that looks right answers an error
Check for a doubled slash. Endpoints such as rest_api already end in / , so …/gmail/v1/ + /users/me is another path. base_url and STATEWEAVE_<APP>_URL have no trailing slash.
WhatsApp: (#131030) Recipient phone number not in allowed list
A test number sends only to its allowed recipients, and a blank sandbox's list is empty. Add the customer's number in edit mode with the test_recipients action, then keep a new version. See WhatsApp .
Claude Code says a tool needs permission
In print mode, Claude Code refuses tools nobody approved. Pass --allowedTools "mcp__<app>__*" for every app the test uses, or use the claude_code.sh script, which does it for you. See Claude Code .
sw mcp config: run r-… has ended
A run's apps stop when it ends, and its MCP servers with them. Start a new run, or open a twin run, and use its config.
The calls show a fault I didn't expect
The test injects faults on purpose. Its page lists them, and the run's page shows each one that acted. See Faults .