Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Symptom
Try

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

Symptom
Try

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

Symptom
Try

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

Symptom
Try

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

Symptom
Try

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

Status
Meaning

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


Last updated: 27 October 2026

Was this helpful?