---
title: "Troubleshoot setup and tests"
description: "Resolve account, discovery, adapter, execution and verification problems."
canonical: "https://agenttwin.si/docs/troubleshooting/"
---

# Troubleshoot setup and tests

Resolve account, discovery, adapter, execution and verification problems.


## Start with the failed boundary

Identify whether the problem is discovery, account connection, preparation, service support, application execution or evidence. Keep the run ID, command, exit code and receipt. Review logs locally and redact sensitive values before sharing them.

## CLI command is missing or Node fails

Run `node --version` and inspect the CLI version/help. Node.js 22.12+ is required. In this repository, `nvm use` selects the checked-in runtime version. A previously published package may lack checkout-only world commands: build and use this repository's CLI rather than assuming the docs describe your old installed package.

## Onboarding says the account could not be loaded

Use **Try again** and confirm the configured AgentTwin API is reachable. A running website does not establish that the separate account API is healthy. Check the browser's failed account request and API server logs. Sign in again if the session is unauthorized. Do not change assertions or fixtures to resolve an account failure.

Browser appearance preferences can be edited without a loaded account; terminal approval and account project checks require the authenticated account. [Dashboard guide](/docs/dashboard/) explains connection state and refresh.

## Discovery finds too much or nothing

Run `init` from the actual application root. Inspect recorded source and dependency evidence before accepting a candidate. Use `--exclude` for unused integrations and rediscover after source changes. Environment keys alone do not create supported adapters. Agent analysis and static discovery produce candidates requiring review.

## Preparation rejects a workflow

Use actual discovery workflow and tool IDs. Include reviewed mappings for every recorded candidate operation. Confirm the entrypoint is built, listed files exist relative to the spec, and the command begins with `node`. Unsupported SDK operations require additional adapter work or a narrower test, not a fabricated mapping marked reviewed.

## Module missing or production requests still occur

Bundle application dependencies before preparation. The runtime does not install them. Override service base URLs with the generated twin endpoint and use its generated token. Inspect the application client's configuration; changing credentials alone does not redirect a production URL. Local application code has host network access, so review execution paths before running.

## HTTP 501 or incomplete coverage

Inspect `contracts` and the receipt's unsupported event. Unknown methods or parameters are deliberately rejected and are not proxied to production. Current Slack support excludes pagination, threads, files and OAuth. Either stay within the implemented contract or implement and validate the missing adapter operation before claiming coverage.

## Requested failure never activated

Check the application's actual method/path and recorded operations against the fault configuration. Ensure the relevant write was reached and the client has a timeout that exposes the delayed response. An untriggered requested fault makes the intended failure test incomplete. Do not remove the fault merely to obtain a passing result.

## Same scenario version cannot be saved

Versions are immutable. Identical content can be saved again; modified content needs a higher version. Check cross-service references for exactly one matching seeded record. Use a new world for a changed baseline and keep the previous version for comparisons.

## World expired or disappeared

Inspect `world status`. Expiration closes endpoints and interrupts active execution. A world cannot be revived after termination or expiry; create another one. Extend a ready world before its TTL elapses. State is held in the host process's memory and is not recoverable after that process is lost.

## Tests pass but the repair is unconvincing

Inspect required outcomes, forbidden effects and protected starting records. Confirm the fault activated and that the test actually reached the failing operation. Compare scenario/specification digests and source changes. Add missing meaningful checks as a separately reviewed test change; do not pretend changing checks proves a source-only repair.

## Receipt is stale after a patch

Run again. For a prepared one-shot bundle, rebuild and prepare the changed source first. For a reusable world, confirm the listed source files are the ones you edited. Verify the new receipt against current source, world and scenario; verification never executes application code.

## Cloud execution is unavailable

Select cloud execution explicitly only when needed. API-managed cloud jobs require an operator-configured runtime. Direct E2B requires your own key and template setup. A gateway can serve accounts and synced evidence without cloud credentials; that does not mean cloud execution is provisioned. PostgreSQL and Redis worlds require cloud execution today.

## Runs is empty

Discover and run in the intended repository, then connect the terminal and sync. Or import a `run.json` receipt manually. Manual imports disappear on page reload and are not uploaded. Browser connection tokens stay in page memory; reconnect if needed and use workspace refresh to load account results.

For the verified end-to-end path, return to [your first verified fix](/docs/quickstart/).