> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/twins/reference/troubleshooting.md).

# 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](/twins/using-twins/connect-your-agent.md#agents-that-need-stdio) |

## 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](/twins/reference/keys-and-limits.md#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](/twins/using-twins/run-your-agent.md#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](/twins/using-twins/connect-your-agent.md#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)                                                                                                                   |

```bash
task=${TWIN_NOW:+"(Today is $TWIN_NOW.) "}$1
```

See [The world's clock](/twins/using-twins/run-your-agent.md#the-worlds-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](/twins/using-twins/connect-your-agent.md#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:

```bash
TWIN_DEBUG=1 twin world create seed.md --folder world       # the error with its traceback
TWIN_LOG_LEVEL=INFO twin world create seed.md --folder world  # more log messages on stderr
```

Then contact your Drizz contact with the command you ran and its output. Remove any tokens or keys first.

## Next

* [CLI reference](/twins/reference/cli.md): every command and option.
* [Keys and limits](/twins/reference/keys-and-limits.md): signing in, keys in CI, and the world limit.
* [Connect your agent](/twins/using-twins/connect-your-agent.md): each client, step by step.

***

*Last updated: 27 October 2026*