deplo.ai/docs

Troubleshooting

Every CLI error message names its own fix — this page collects them with the cause behind each one. For deployment failures themselves (builds, env vars, provider errors), see the platform Troubleshooting guide.

Platform-side failures — OAuth, builds, invalid API keys — are covered in Guides → Troubleshooting. Below are the errors the CLI itself produces.

Authentication#

text
✗ not signed in — run deplo login

Cause: no token found — neither the DEPLO_TOKEN environment variable nor ~/.config/deplo/config.json has one. In non-interactive deploys the message reads ✗ not signed in — run deplo login (or set DEPLO_TOKEN).
Fix: run deplo login; in CI, set the DEPLO_TOKEN secret (see CI Usage). Interactive deplo offers to sign you in inline.

text
✗ token expired or revoked — run deplo login

Cause: the API returned 401 — the stored token was revoked at Settings → CLI tokens, or it was minted by a different deplo instance than the one DEPLO_API_URL now points at.
Fix: deplo login again. If you use DEPLO_API_URL, make sure the token and the API belong to the same instance (Configuration).

text
✗ that token was not accepted — create a new one at deplo.in → Settings → CLI tokens

Cause: the token pasted to deplo login --token failed verification — truncated on copy, already revoked, or not a dpl_ CLI token (a JWT from browser dev tools will not work).
Fix: create a fresh token at deplo.in → Settings → CLI tokens and paste it whole. The masked prompt (running --token without a value) avoids shell-history and quoting accidents.

Login hand-off#

text
✗ Timed out waiting for the browser (5 minutes). Try `deplo login --token` instead.

Cause: the CLI's loopback listener never received the authorization callback — the authorize click never happened, or the browser runs somewhere that cannot reach the terminal's 127.0.0.1 (SSH session, container, remote dev box).
Fix: on the same machine, re-run and complete the authorization within five minutes. On remote machines the hand-off cannot work by design (the token is only ever delivered to loopback) — use deplo login --token (Authentication).

The browser never opened. Opening is best-effort (open / xdg-open / start); on minimal Linux boxes there may be nothing to open with. The CLI prints the authorization URL first — → opening https://www.deplo.in/cli-auth?… — so you can copy it into any local browser. If the browser is on a different machine, use deplo login --token, and deplo connect vercel --print-url for the Vercel authorization.

Repository matching#

text
✗ this directory has no GitHub remote — run inside a cloned repo, or deploy from the dashboard

Cause: the current directory is not a git repository, or its origin remote does not point at github.com. The CLI resolves the repo from git remote get-url origin.
Fix: cd into the cloned repo, or add the remote: git remote add origin git@github.com:you/your-repo.git. Both SSH and HTTPS remote URLs work.

text
✗ acme/storefront is not visible to deplo
  private repo? install the GitHub App: deplo.in → dashboard → repositories → configure access

Cause: the remote resolved to a repository the platform cannot see, even after the CLI auto-synced your repo list from GitHub. Usually a private repository not covered by the deplo GitHub App, or a repo owned by an organization you have not granted access for.
Fix: install or reconfigure the GitHub App from the dashboard's Repositories page so it covers the repo, then re-run deplo. Details in Integrations → GitHub.

Provider connections#

text
✗ vercel is not connected — run deplo connect vercel
✗ render is not connected — run deplo connect render

Cause: a non-interactive deploy (--yes or no TTY) found a provider missing. Interactively, deplo would have offered to connect it inline.
Fix: run the named command once from any terminal; connections are stored server-side, so CI picks them up immediately. deplo whoami shows the checklist.

text
✗ timed out waiting for the connection (5 minutes)

Cause: deplo connect vercel polls until the integration appears; the authorization was never completed in the browser.
Fix: re-run and finish the OAuth flow. On a browserless machine, use deplo connect vercel --print-url, open the link anywhere, authorize, then confirm with deplo whoami.

Deployment failed#

text
✗ Deployment failed — build failed
  full log + AI diagnosis: deplo.in/dashboard/deployments/dep_8f31a2

Cause: the deployment itself failed — the CLI already streamed the failing log lines (in red) above this message.
Fix: open the printed dashboard URL. The deployment page holds the full log plus the AI diagnosis — likely cause, affected file, suggested fix — and a copy-paste prompt for your AI coding tool. Fix, push, deploy again; services are reused idempotently. See Deployments.

Connectivity and base URL#

text
✗ fetch failed
✗ Request failed (404)

Cause: the CLI could not reach the API, or reached the wrong one. Nine times out of ten a leftover DEPLO_API_URL (or an apiUrl in ~/.config/deplo/config.json) points at a stopped local instance or omits the /api/v1 path.
Fix: check echo $DEPLO_API_URL and the config file; unset the override or correct it to a full base like https://www.deplo.in/api/v1. Corporate proxies and captive networks can also block the request — try another network. Precedence rules are in Configuration.

Still stuck?
deplo whoami is the fastest health check: it exercises the token, the API base URL, and both provider connections in one command.