Troubleshooting

Real errors you may hit and what to do about them. Most are the CLI telling you exactly which command to run next.

not logged in — run dst login first

No bearer token is configured. Either run dst login (interactive), or in CI set DESTESI_API_KEY to an API key. Confirm with dst whoami.

invalid or expired token (HTTP 401) — run dst login to re-authenticate

dst whoami got a token the server rejected. Sessions don’t last forever, and a revoked key fails the same way. Run dst login again, or rotate the DESTESI_API_KEY you’re passing in CI. Mint a fresh one with dst api-key create.

no active workspace — run dst workspace switch <name> first

Product commands run against your active workspace, and none is selected. Run:

dst workspace list
dst workspace switch my-workspace

In CI, set DESTESI_WORKSPACE=my-workspace instead of switching interactively.

workspace "..." not found — run dst workspace list to see your workspaces

The slug or id you passed doesn’t match a workspace you belong to. dst workspace list shows the exact slugs (and marks the active one with *). Workspaces are matched by slug — the lowercase, URL-safe handle — so use that.

Note

If you used Destesi before workspaces existed, an older config may print: notice: legacy active_org no longer applies — run dst workspace switch <slug> to set a workspace. The CLI clears the stale value automatically; just select a workspace once.

execute request: ... (Is the API running? Check --api-url)

The CLI couldn’t reach the API host. Check that api_url in ~/.dst/config.yaml (or DESTESI_API_URL) points at a reachable host, or pass --api-url for one call. This commonly appears when a DESTESI_API_URL is set to a host that isn’t up.

dst login hangs or never approves

dst login initiates a browser approval and polls for the result. If the browser didn’t open, copy the verification URL it printed and open it manually, then enter the code shown. On a headless host this is the expected path. If polling keeps failing, the CLI surfaces repeated transport or non-JSON errors after a few attempts — that usually means the API host is wrong or down (see the previous entry).

dst preview wait exits non-zero

dst preview wait uses exit codes to report the outcome, which is by design for CI:

Exit	Meaning	What to do
0	Healthy	Nothing — the preview is up; its public URL is printed.
1	Failed	The preview broke. The command prints a trace (status, events, log tail). Run dst preview trace <id> for the full picture.
2	Timeout	Still building when --timeout elapsed. Raise --timeout, or run dst preview trace <id> to see where it’s stuck.
3	Deleted	The preview was deleted while waiting.

--third-party-app is required when using --repo

Previewing a GitHub repo needs a connected GitHub account to fetch the source. Connect one, then pass its id:

dst third-party-apps connect-github      # or: add-github --token <pat>
dst third-party-apps list                 # copy the id
dst preview create --repo owner/name --third-party-app <id> ...

For credentials shared across the whole suite, see Connect.

--connector-id (clone from remote) or --from-snap (fork from branch) is required

dst snap create needs to know where the branch comes from. Pass --connector-id <id> to clone a registered remote, or --from-snap <id> to fork an existing branch. List remotes with dst snap remote list and branches with dst snap list.

no remote named "..." in workspace ...

A --from-remote <name> didn’t match any remote in the active workspace. dst snap remote list shows the names and ids; pass an exact match or the remote id.

dst snap trace shows nothing

SQL tracing is opt-in. The branch’s proxy must have been started with SNAP_TRACE_SQL=1 — without it the trace ring stays empty. If psql isn’t on your PATH, the command prints the psql ... SNAP TRACE invocation for you to run yourself (or use --print to always just print it).

dst review list reports the feature is disabled

dst review list reads reviews from an API instance that has the GitHub App wired up. If you’re pointed at an instance without it, the command says so. Point --api-url (or DESTESI_API_URL) at an instance that has GitHub App support, and make sure the repo opted in via review.enabled: true in .destesi.yml on its default branch.

dst mcp: Claude Code CLI not found

dst mcp adds the server to Claude Code automatically only when the claude CLI is on your PATH. If it isn’t, the command prints the manual claude mcp add instructions and tells you where your token lives (~/.dst/config.yaml, field auth_token) — it deliberately avoids echoing the token to your shell history.

dst upgrade: can’t reach the release host

dst upgrade downloads from a release host and verifies the SHA-256 checksum before replacing the binary. If the host is unreachable, point it at a mirror:

DST_DOWNLOAD_URL=https://your-mirror dst upgrade

A checksum mismatch aborts the upgrade — that’s the integrity check doing its job. DST_SKIP_CHECKSUM=1 bypasses it, but only use that if you understand the risk (e.g. a known publishing skew). You can always reinstall cleanly with the install script:

curl -fsSL https://get.destesi.io/install.sh | sh

.destesi.yml already exists ... pass --force to overwrite

dst init won’t clobber an existing config by default. Re-run with --force to regenerate it.

dst installed but command not found

The install script drops dst in /usr/local/bin, or ~/.local/bin when that isn’t writable. If it chose ~/.local/bin, add it to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Override the target directory with DST_INSTALL_DIR when running the install script.

Where next?

Command referenceEvery command, flag, config field, and environment variable dst recognizes.

ConceptsHow auth, workspaces, and output formats fit together.

SnapThe branching engine behind dst snap.

PreviewEphemeral per-PR environments behind dst preview.

Code ReviewAI reviews surfaced by dst review.

MCPThe agent toolset dst mcp installs.