# Troubleshooting

The problems people hit most often, and how to get past them.

## “CircuitTwin isn’t available in your country yet”

CircuitTwin is available in the United States only. If you picked the wrong country when you signed in, choose **Change my location**.

## The sign-in code did not arrive

Check your spam folder, then choose **Resend code**. You can ask for a code once every 20 seconds and five times in ten minutes.

## “a CircuitTwin account is required”

Every ct command needs a signed-in account. Run `ct login --server <url>`, or set both `CT_SERVER` and `CT_TOKEN`. `ct login --status` shows whether the stored token is still accepted; a revoked or expired token needs a new one.

## “CT\_TOKEN is set without CT\_SERVER”

A token from the environment is only sent to the server `CT_SERVER` names. Set `CT_SERVER` too, or unset `CT_TOKEN` to use your `ct login` sign-in.

## ct run exits 2: unknown board or firmware that does not fit

Nothing ran. An unknown `--board` id prints the list of built-in and derived boards. Check that the ELF was built for that MCU (memory map, core) and that every `--device` names a twin the catalog has (`ct catalog find <part>`).

## ct run exits 4: inconclusive

The run completed, but the firmware depended on a peripheral the twin does not model, so the result cannot count as a pass. The report names the unsupported peripherals. Generate the twin with more documents (`ct twin generate ... --with` the reference manual), or tell us which part you need.

## ct run exits 1 without reaching --until

The target text never appeared within `--max-ms` of virtual time, or the firmware faulted. Raise the budget, check the console in the report, and debug it: `ct gdb-server --catch-faults` stops on the fault entry. See [Debug in your IDE](https://circuittwin.ai/docs/ide).

## ct scene run refuses an SPI or I2C link (scene.link.node-unsupported)

The SPI slave or I2C target needs a twin with that mode: the STM32 SPI and I2C models and the Nordic SPIS and TWIS today. UART links run with every UART model. See [Systems and scenes](https://circuittwin.ai/docs/scenes).

## \--timing cycle-approximate or --uninitialized-memory seeded is refused

Both are opt-in and provisional, and they are refused (exit 2) for a part without a timing profile or without recorded undefined cells. Leave them out to run with the defaults.

## The IDE cannot connect to localhost:3333

Make sure `ct gdb-server` (or `ct gdb-bridge`) is running and the port matches; another debug server may already hold port 3333, so try `--port 0` for a free one and rerun `ct ide setup --port`. The server listens on loopback only unless started with `--allow-remote`.

## CI cannot find the board or system

On the hosted service, suites reference systems by id, and the system must exist in the workspace the token belongs to. Board and scenario files cannot be referenced on the server. Check with `ct cloud whoami` which workspace the token is bound to.

## Still stuck?

Email [support@circuittwin.ai](mailto:support@circuittwin.ai) with the command, its `--json` output and the ct version (`ct --version`).