# Troubleshooting The errors you are most likely to hit, what each one means, and the fix — organised by what you saw, not by what went wrong. Organised by symptom. Every message quoted here is one the CLI or the portal actually prints. ## The deploy was rejected **`--site is required (a site name or id; see one9x pages list)`** The flag is missing. `one9x pages list` shows what you have. **`no site "mysite" for this account`** — followed by the sites you do have. Usually a typo, or the site was created on a different account. Create it with `one9x pages create mysite`; a release will not create one for you, because a typo would then publish your build to a brand-new address instead of the one you meant. **`./dist contains no deployable files`** The folder is empty, does not exist, or everything in it was filtered out. Dot-paths are never uploaded — if your build writes to `.output/` or `.svelte-kit/`, point the release at the folder *inside* it. Over-broad `--exclude` patterns are the other cause. **`index "/index.html" is not in the deploy`** `--spa` (or `--index`) names a file the build did not produce, at the exact path given. Check the file is really at the root of the folder you are deploying. **`error page for 404 points at "/404.html", which is not in the deploy`** Same thing for `--error`. The path is relative to the deployed folder, so a page built to `/404/index.html` will not match `--error 404:/404.html`. **`--spa and --index are the same mapping; use one`** They are one setting. `--spa` is `--index /index.html`. **`invalid --error "404" (want :, e.g. 404:/404.html)`** The colon and the path are both required. ## A limit stopped it All three are checked before anything uploads, so nothing is half-deployed: - **`this deploy has 812 files, and your plan allows 500 per site`** - **`"/video/intro.mp4" is 18.4 MiB, and your plan's limit is 10 MiB per file`** - **`this deploy needs 240 MiB and your account is using 0.97 GiB of its 1 GiB`** `--exclude '*.map'` and excluding a stray `node_modules` fix most file-count failures. The numbers are on [Limits](/docs/limits). **`5 tagged releases already (max 5) — delete one to free a slot`** Tagged releases never age out, which is what the cap bounds. `one9x pages releases rm --site ` frees one. **`tag already in use on another release of this site`** Tags are unique per site. Remove it from the other release or pick a new name. ## Sign-in and tokens **`portal 4xx: … — run one9x update`** The binary is older than the portal will talk to. `one9x update` replaces it in place. **A pipeline that worked for months suddenly 401s.** Machine tokens last 90 days by default. `one9x tokens list` shows expiry; `one9x tokens extend ` pushes it out **without changing the secret**, so nothing stored in CI has to be updated. This is the single most common way a working deploy stops working. **`the 'token' input is empty`** (GitHub Action) The secret is missing or misnamed. Check it is set on the repository or organisation, and that an organisation secret's visibility includes this repo. ## Choosing a release **`no release matches that ref`** `--to` takes a release number (`v6`), a tag, or a version-hash prefix. `one9x pages releases list --site ` shows all three for every release. **`ref is ambiguous, use a longer prefix`** A hash prefix matched more than one release. Add characters, or use the release number. **`--to is required (a release like v6, a tag, or --to "" for the previous release)`** `--to ""` is the one you want right after a bad deploy. ## The deploy worked, the site is wrong **The homepage loads, every internal link 404s.** The build wrote `about.html` where a request for `/about` needs `about/index.html`. Pages serves paths, not routes. Next.js needs `trailingSlash: true`; SvelteKit needs `trailingSlash = 'always'` — see [Frameworks](/docs/frameworks). **A deep link 404s on hard refresh, but works when clicked.** A client-side router without `--spa`. The app is fine; the first request never reaches it. See [SPA mode](/docs/spa-and-errors). **Blank page, 404 on every script and stylesheet.** The build is emitting asset URLs under a subdirectory — a `base`, `homepage` or `pathPrefix` left over from a project-subdirectory host. On One9x you are at the root of your own subdomain, so it should be `/`. **A file you expected is missing.** Anything beginning with a dot is left on your machine. `.well-known` is the one exception, so `assetlinks.json` and `apple-app-site-association` do deploy. **The site's own address says nothing is live yet.** The site exists and the name is yours — that page is what an address with no published release shows, and it prints the command that publishes. Usually it means a release was staged rather than deployed: `one9x pages releases --site ` will show it, and `one9x pages deploy --site --to v1` puts it live. The release's own preview URL works in the meantime. **A one-line edit reports hundreds of changed files.** `one9x pages diff` against live before publishing. It usually means the build changed rather than the content — a bumped asset hash, or a folder that should have been excluded. ## Custom domains **`verify` fails right after adding the record.** Verification reads public resolvers, not ours, so give a new record a minute. The failure message names what we actually saw, which is normally enough to spot a typo or a proxy answering for the name. **The apex will not take a CNAME.** DNS does not allow one there. Use ALIAS or ANAME if your provider has it, and the A record if it does not — both are on [Custom domains](/docs/domains). **`"example.com" is already unlinked`** It is off the site but still yours. `one9x domains link` re-attaches it, usually instantly, because the certificate was kept. ## GitHub Actions **`input 'deploy' must be exactly true or false, got 'yes'`** Booleans are checked rather than coerced, because a value read as `false` would silently stage a release that was meant to go live. **`dir 'dist' does not exist`** The build step did not run, or wrote somewhere else. [Frameworks](/docs/frameworks) has the folder per framework. **The job was skipped entirely.** A workflow gated on a variable that is not set. In the [template repositories](/docs/frameworks) that is `ONE9X_SITE`, deliberately — so a fresh copy does not fail before it is configured. **No preview comment on a pull request from a fork.** GitHub gives fork pull requests a read-only token by design, so commenting cannot work there. The action skips it rather than failing a contributor's PR. ## Still stuck Every command takes `--json`, which puts a machine-readable result on stdout and progress on stderr — useful to paste when asking for help. Then [contact us](/contact).