> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.docs.xano.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find the symptom you are seeing, from a first deploy that fails on your platform to a refused promote or an expired ephemeral, and the command that fixes it.

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](/help/exit-codes-and-outcomes).

<Tip>
  Set `XANOSDK_DEBUG=1` to append the untouched server response to any failure message.
</Tip>

## 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](/start/connect-to-xano) first:

```bash theme={null}
npm run xano:deploy:ephemeral
```

Use that script wherever a page says `npm run xano:deploy`. See
[where the Engine differs today](/run/xano-engine#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](/build/typed-frontend#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:

```bash theme={null}
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](/ship/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](/govern/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](/ship/promote-and-go-live#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:

```bash theme={null}
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](/govern/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](/help/exit-codes-and-outcomes#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](/ship/releases#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](/govern/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:

```bash theme={null}
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](/run/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](/ship/releases#when-ephemerals-are-off-stage-on-a-xano-branch).

## 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:

```bash theme={null}
npm run xano:deploy
```

Treat rows on the Engine as scratch data. See
[where the Engine differs today](/run/xano-engine#where-the-engine-differs-today).

## Still stuck

```bash theme={null}
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.

## Next

* What each exit code means: [Exit codes and outcomes](/help/exit-codes-and-outcomes).
* Every `SDK_*` code: [Warning and error codes](/reference/error-codes).
* Terms on this page: [Glossary](/help/glossary).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.