Troubleshooting
Bookmark-worthy fixes for the friction points customers hit most.
App stuck in `deploying` state forever
Cloud Build sometimes finishes before the platform records the final status (or a revision boots slowly). Check the actual state with the apps list:
$ leash apps
NAME STATUS URL
my-app deployed https://my-app.un.leash.build
For machine-readable output, pipe through jq:
$ leash apps --json | jq '.[] | select(.name=="my-app")'
To poll for an app to come up, use leash status <app> --wait — it polls every 2s until the app is active. If a deploy is genuinely stuck (>5 minutes after build success) — file an issue with the deployment ID.
`leash dev` exits with 'API error: HTTP 200'
The CLI parsed a successful HTTP response but couldn't deserialize the body — almost always because your local JWT is from an older platform schema and the platform is returning a shape the CLI version doesn't recognize.
Fix: refresh your token.
$ leash logout
$ leash login
To get unblocked right now, skip secret resolution:
$ leash dev --no-secrets
--no-secrets runs with whatever's in your local environment and skips fetching platform secrets entirely.
Adding a custom MCP server
Need an integration Leash doesn't pre-build (Intercom, in-house tooling, a third-party MCP)? Register the URL + bearer on the dashboard, fetch the config from the SDK, plug into your MCP client.
Full recipe: Custom MCP cookbook.
`.env.example` required for env var injection
leash dev and leash deploy read .env.example as the manifest of which env keys to inject. No file, no injection (you'll see an error pointing at the missing file).
Create the file with placeholder values — Leash only reads the key names. Commit it to git so every machine on the team uses the same manifest.
Full contract: CLI / Secrets.
Re-auth after upgrading the CLI
New CLI releases sometimes carry new JWT claims (org role, lane, billing state). Tokens issued by an older CLI may be missing those claims, causing 401s on calls that worked yesterday.
Run a logout + login cycle after every CLI upgrade:
$ leash logout && leash login
The token is short-lived but the cookie is cached locally — explicit logout is the fastest way to force a fresh exchange.
Why does my app have a random subdomain suffix?
Subdomains are unique across all of un.leash.build. If your preferred name is taken (by another org or a reserved keyword), the platform picks an available variant by appending a short random suffix — my-app-7k2.un.leash.build. The subdomain is immutable after first deploy, so the suffix sticks.
To avoid the suffix, pick a more specific name (prefix it with your org slug) before running leash init, or delete the app and re-init under a free subdomain if you haven't shared the URL yet.