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.
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.
--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 with the command, its --json output and the ct version (ct --version).