Troubleshooting

Each section below names one symptom — an error string or an HTTP status — and gives its cause and its fix. Sections are self-contained and can be read in any order.

The three most common: Unauthorized means the CLI has no credential for that site; 410 Gone means an anonymous deploy passed its 14-day expiry and was deleted; 403 on deploy means the upload was rejected by content screening.

Unauthorized on flypod update or flypod rollback

Why: you are not logged in, the saved manage_token is wrong or missing, or the site is owned by another account.

Fix: log in, pass the token explicitly, or confirm ownership.

flypod login
# or
flypod update ./dist --token <manage_token>

If you still get Unauthorized while logged in, the site belongs to a different account, so you cannot manage it.

flypod update says the site is gone (404)

Why: the local folder-to-site link is stale. The site it pointed at expired or was deleted.

Fix: flypod auto-drops the stale link. Just deploy a fresh site.

flypod

flypod update succeeded but flypod versions didn't grow

Why: expected. A version id is the hash of the deploy's content, so re-running flypod update with byte-identical files resolves to the version that already exists. Nothing is re-stored and no new version row is created — but the upload still happens and the CLI still reports the version as live, so the command looks identical either way. There is no "nothing changed" message.

Fix: nothing is broken. This is what makes flypod update safe to call on every iteration of an agent loop or a CI job: an unchanged run cannot pile up versions. If you want to skip the upload itself, gate the call on your own change detection.

flypod rollback refuses

Why: there is only one version, or the live version is already the oldest one. There is nowhere to roll back to.

Fix: deploy a new version first, then roll back.

flypod update ./dist

Visiting a site returns 410 Gone

Why: an anonymous deploy expired. Anonymous sites have a 14-day TTL.

Fix: redeploy. To avoid expiry next time, deploy while logged in. To save sites you already deployed anonymously, run flypod login — it auto-claims every anonymous site this CLI remembers. See /docs/concepts/ephemerality.

A site returns 451

Why: an operator disabled the site for abuse.

Fix: nothing self-serve. The site was taken down deliberately.

A deploy is rejected with 403

Why: the abuse guard flagged the content (for example a credential or login form whose action posts to another domain), or a bot challenge failed.

Fix: remove the flagged content (e.g. point form actions at the same origin), or retry the challenge.

Upload rejected as too large

Why: the deploy exceeds the size cap: 200 files / 10 MB uncompressed / 5 MB zip per deploy.

Fix: trim the build (drop source maps, large media, or unused assets) so it fits under the cap.

No build directory found

Why: auto-detection looks for an index.html inside one of dist/, build/, out/, .output/public, .vercel/output/static, public/, or _site/, and found none.

Fix: pass the directory explicitly.

flypod ./path

Markdown didn't render as a docs site

Why: rendering only happens when there is no index.html at the deploy root. If an index.html is present, flypod serves the files as-is and skips rendering.

Fix: remove the root index.html (or deploy a directory without one) to get the rendered docs site. See /docs/guides/render-markdown.