Troubleshooting

Most of what the CLI prints when it stops is a refusal, not a crash: it checked something, did not like the answer, and wrote nothing rather than doing damage quietly. Find your symptom below. For what each exit code means, see Exit codes and outcomes.

Set XANOSDK_DEBUG=1 to append the untouched server response to any failure message.

The first deploy fails on this platform

The Xano Engine runs on macOS (Apple silicon) and Linux (x64, arm64). On Windows or an Intel Mac, a deploy to the Engine is refused before anything compiles:

✗ There is no Xano Engine build for darwin x64 — it runs on darwin-arm64, linux-x64, linux-arm64 and nothing else, so there is no engine to run here. Deploy from one of those machines, or add `--ephemeral`: `xanosdk deploy --ephemeral` reaches an ephemeral from anywhere.

Deploy the same code to an ephemeral in Xano’s cloud instead. It needs a Xano account, so connect to Xano first:

npm run xano:deploy:ephemeral

Use that script wherever a page says npm run xano:deploy. See where the Engine differs today.

The frontend shows no backend

A deploy that publishes no static site writes the backend’s URL into .env.local as VITE_XANO_HOST. Vite reads that file only when the dev server starts.

The dev server was already running. Stop npm run dev and start it again.

Your repo does not gitignore .env.local. The deploy refuses to write a per-machine URL into a file git would commit, and warns instead:

Not pointing your dev server at the deploy: git does not ignore .env.local, and this would put a per-machine backend URL into a file your repo commits.
Add `.env.local` to your ignore rules (the scaffold's .gitignore lists it), then re-run — or pass `--no-dev-env` to skip this step for good.
The backend is deployed either way: set VITE_XANO_HOST=http://127.0.0.1:53358 yourself to reach it.

Add .env.local to .gitignore, deploy again, and restart the dev server.

You deployed with --no-dev-env. Set VITE_XANO_HOST in .env.local yourself.

See The backend URL.

A release is refused from the Engine

A release is cut on your Xano instance, which cannot reach an Engine on your machine. Naming the Engine is refused, and so is a bare release create right after a deploy to the Engine, because a bare command follows the backend you last deployed to:

✗ "local" names a Xano Engine, which `npx xanosdk release create` cannot serve: the cut runs on the instance, which cannot reach an engine on this machine. Sources are workspace, ephemeral, ephemeral:<name>, or tenant:<name>.

Deploy to an ephemeral, then cut the release from it:

npx xanosdk deploy ./xano/index.ts --ephemeral --test   # deploy to an ephemeral, then run its tests
npx xanosdk release create v1.4.0                        # cut from that ephemeral

See Releases.

Promote is refused

Each of these exits 2, lands nothing (except where noted), and is not waived by --yes.

What you see	Why	What to do
`SDK_SHARED_SCHEMA_CHANGE`: “Refusing to promote “v1.4.0”: it alters a table your live workspace serves from.”	Tables are shared by every Xano branch, so the change reaches live as soon as the release lands, before any `--set-live`.	Cut a release without the change, or pass `--allow-shared-schema-changes` once you accept it. See Schema changes.
`SDK_SHARED_SCHEMA_CHANGE` with “whether it changes your workspace’s tables is unknown”	The table read failed. A failed read is not evidence of no change.	Run it again when the instance answers.
`SDK_LIVE_BRANCH_MISMATCH`	`--expect-live` named a Xano branch that is not live. `details.conflictsWith.live` names the one that is.	Check what is live with `npx xanosdk workspace branch list`, then rerun with the right label. If live moved between the check and the switch, the new Xano branch stays landed but is not served.
`SDK_IDENTITY_CONFLICT`	The workspace already uses a name in the release for a different object, or a public URL slug the release pins is served by another workspace.	A release’s identities are fixed when it is cut: fix the project, then cut and promote a new release.
`verify: no` in the result, with “Landed v1.4.0 on branch … but …”	The release landed, then the read-back found a declared object missing or a pinned slug served under another value. `--set-live` was not applied.	Read the message, fix the cause, and promote again. Delete the landed Xano branch if you do not want it.

Full detail: What promote refuses.

`SDK_WORKSPACE_CHANGED`

deploy --to workspace refuses to overwrite objects that someone changed in Xano since the last sync:

✗ Refusing to deploy to branch "v1": 1 object was changed in Xano since the last sync (pull, 2026-10-05T13:36:31.000Z), and this deploy would overwrite it:
  query:GET list (apiGroup orders)

Bring the change into this project first (`npx xanosdk pull workspace`, then commit and deploy), or deploy over it: `npx xanosdk deploy ./xano/index.ts --to workspace --overwrite`.

Bring the edit into your code, commit it, and deploy again:

npx xanosdk pull workspace
git add xano && git commit -m "Pull edits made in Xano"
npx xanosdk deploy ./xano/index.ts --to workspace

Pass --overwrite only when you mean to discard the edit made in Xano. See Drift.

Exit 9: the outcome is unknown

A write was sent and the answer was lost: a timeout, a dropped connection, a server error, or Ctrl-C mid-write. It may have landed. Do not run the same command again: run the resolveWith command it printed, and treat “absent” as proof only after resolveNotBefore.

After	Read with
`release create`	`npx xanosdk release list`
`promote`	`npx xanosdk workspace branch list`
`tenant deploy`	`npx xanosdk tenant get <name>`

See Operation outcome.

`SDK_RELEASE_NAME_TAKEN`, or a release with a suffix

Release names are used once. You meet this code in two ways:

The name was already taken. Nothing was cut. Cut a new name, such as v1.4.1.

✗ A release named "v1.4.0" already exists (cut 2026-10-12T09:13:16.000Z from ephemeral e4f2-9ab1). Releases are not replaced — cut a new name.

The name was taken while the cut ran. The platform stored your cut as v1.4.0- plus four hex characters and reported success. release create catches that, refuses rather than report success, and prints the release delete that removes the stray copy. Anything that addresses v1.4.0 does not reach it.

After an exit 9, look for both spellings in npx xanosdk release list before you cut again. See Name a release.

`xano.lock` has conflict markers

Every command that reads the lock refuses a file with unresolved merge markers:

✗ Invalid lock file xano/xano.lock: it holds unresolved merge-conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`). Resolve it as the union of both sides: keep every entry under `objects` (and `landed`) from each, delete the markers, and fix the commas. …

Keep both sides’ entries, delete the markers, and run npm run xano:check. The full recipe is in Git and merges.

An ephemeral expired (exit 8)

An ephemeral lives 1 hour by default (--expires-hours sets 1 to 24 when a deploy creates it). A bare command that follows an expired one exits 8 and clears the project’s record of it:

✗ Ephemeral "e4f2-9ab1" has expired. Run `npx xanosdk deploy --ephemeral` to create a fresh one (cleared this project's record of it).

Deploy a new one:

npm run xano:deploy:ephemeral

A release cut from an ephemeral survives its expiry, so cut what you want to keep before it goes. See Ephemerals.

Ephemerals are turned off on this instance

Not every instance has ephemerals enabled. A deploy to one says so:

✗ Ephemeral environments are not enabled on this instance, so there is nothing for `npx xanosdk deploy ./xano/index.ts --ephemeral` to create.
Ask whoever administers the instance to enable them.

The Engine, npx xanosdk export and npx xanosdk preflight still work. To ship without an ephemeral, stage on a Xano branch of your workspace and cut the release from it: When ephemerals are off.

The Engine restarted empty after `local update`

Rows on the Engine do not survive an update, a version change or a restart:

Restarted xanosdk-4f2a91c03b7e on v0.1.26. It starts empty — run your deploy to seed it.

Deploy again to seed it:

npm run xano:deploy

Treat rows on the Engine as scratch data. See where the Engine differs today.

Still stuck

npx xanosdk status              # who you are, which workspace, which backend this project last deployed to
npx xanosdk workspace details   # the instance and workspace your credential is bound to
npx xanosdk version             # the installed @xano/sdk

Then run the failing command again with XANOSDK_DEBUG=1 for the raw server response.

What each exit code means: Exit codes and outcomes.
Every SDK_* code: Warning and error codes.
Terms on this page: Glossary.

Get started

Build

Run locally

Deploy to Xano

Govern

Use with AI tools

Help

The first deploy fails on this platform

The frontend shows no backend

A release is refused from the Engine

Promote is refused

`SDK_WORKSPACE_CHANGED`

Exit 9: the outcome is unknown

`SDK_RELEASE_NAME_TAKEN`, or a release with a suffix

`xano.lock` has conflict markers

An ephemeral expired (exit 8)

Ephemerals are turned off on this instance

The Engine restarted empty after `local update`

Still stuck

Next

​The first deploy fails on this platform

​The frontend shows no backend

​A release is refused from the Engine

​Promote is refused

​SDK_WORKSPACE_CHANGED

​Exit 9: the outcome is unknown

​SDK_RELEASE_NAME_TAKEN, or a release with a suffix

​xano.lock has conflict markers

​An ephemeral expired (exit 8)

​Ephemerals are turned off on this instance

​The Engine restarted empty after local update

​Still stuck

​Next

The first deploy fails on this platform

The frontend shows no backend

A release is refused from the Engine

Promote is refused

`SDK_WORKSPACE_CHANGED`

Exit 9: the outcome is unknown

`SDK_RELEASE_NAME_TAKEN`, or a release with a suffix

`xano.lock` has conflict markers

An ephemeral expired (exit 8)

Ephemerals are turned off on this instance

The Engine restarted empty after `local update`

Still stuck

Next