Troubleshooting
The usual errors when making worlds and connecting agents, what they mean, and what to do.
Find the symptom, apply the fix.
"the twin ... is down" (exit 69)
the service, not your agent or your setup. Try again in a few minutes
"not signed in" (exit 4)
run twin whoami, then twin login
Your organization is at its world limit
twin world list, then delete worlds you are done with
Your agent's model refuses the twin's tools
connect it through the stdio bridge
The twin service
error: the twin ... is down (HTTP 503 ...), exit status 69
Try again in a few minutes. Every command asks the twin's /health before it starts, twice, three seconds apart. Nothing was made, and no agent ran. A CI job can tell an outage from a real failure by the 69
You know the twin's /health is wrong
Set TWIN_SKIP_HEALTH=1 to skip the check
The message looks like this:
error: the twin at https://twins.drizz.dev/... is down (HTTP 503 Service Temporarily
Unavailable). Nothing was run: this is the service, not your agent or your setup --
try again in a few minutes.Sign-in and keys
not signed in -- run twin login, exit status 4
No key is kept on this machine, or the twin refused yours (wrong, expired or revoked). Run twin whoami: it says where the key is kept and whether the twin takes it. Then run twin login
The same, in CI
Set a current key in TWINS_API_KEY, or echo "$KEY" | twin login --with-key -
The sign-in says your email has no access yet
Ask your Drizz contact. Your organization's access comes from Drizz
Worlds
Your organization is at its world limit (25 unless an admin raised it)
twin world list shows how many are in use. Delete the ones you are done with: twin world cleanup --label <label> --dry-run, then the same with --yes. Use a shorter --lease for short runs. See Keys and limits
a world the twin did not delete keeps its folder: run delete again
The twin could not delete the world, so its folder is kept. Run twin world delete <folder> again. It exits with 69 when the twin is down, and 2 otherwise
Your agent's calls are mixed with your own
twin api and twin world save read the world as its owner, and their calls go in the record. Read twin world calls first. twin world snapshot is not in the record: use it to keep a world without adding calls
A fault is refused, or never fires
Use the calendar twin's own names: events.create, not events.insert; events.update, not events.patch; events.remove, not events.delete. Give each fault its own attempt. A fault kind the twin does not offer yet (such as drop_item) is skipped with a warning. See Inject faults
Connecting your agent
Your agent's model refuses the twin's tools
The twin names its tools as Google does (events.list), and OpenAI and Anthropic refuse a tool name with a dot. Connect through the stdio bridge: it lists the tools as events_list. See Agents that need stdio
Your agent gets the day wrong
The world's clock is pinned by the seed file's now:, and your agent's model uses the real date. Pass TWIN_NOW to the model at the start of the task (see below)
See The world's clock.
Scalekit
the credential presented is not one this twin issued (401)
The twin is not down. Your Scalekit connector is sending an old token, for example after you made a new world. Update the connector's Server URL and token in Scalekit, then reconnect
"json-pointer not found"
Some imported schemas carry a $ref to #/$defs/... with no $defs block, and strict providers (OpenAI, Groq) refuse the whole tool list. Replace the dangling $ref with {} before you hand the schema to the model
"Custom connectors are not supported yet"
Scalekit's Virtual MCP does not take custom connectors, and a twin is added as one. Reach the twin through the Scalekit SDK (execute_tool). See Scalekit agents
Exit codes
0
it worked
2
usage or setup error: a wrong option, a missing file or folder. Also twin api when the twin answers with an error
4
sign-in needed: not signed in, or the twin refused the key
69
a Drizz service is down. Not your agent, not your setup
130
stopped with Ctrl-C. The worlds the command made were deleted on the way out
143
stopped by SIGTERM (a cancelled CI job), cleaned up the same way
twin world run ends with your agent's own exit status. twin help exit-codes prints this table.
Still stuck
Run the command again with more detail:
Then contact your Drizz contact with the command you ran and its output. Remove any tokens or keys first.
Next
CLI reference: every command and option.
Keys and limits: signing in, keys in CI, and the world limit.
Connect your agent: each client, step by step.
Last updated: 27 October 2026
Was this helpful?