Troubleshooting

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 <code>:<path>, 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.

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 <ref> --site <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 <id> 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 <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.

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.

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 <site> will show it, and one9x pages deploy --site <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.

"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 has the folder per framework.

The job was skipped entirely. A workflow gated on a variable that is not set. In the template repositories 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.