Troubleshooting

Troubleshooting

The CLI prints success data to stdout. With --json, success is one JSON object or array. Errors are printed to stderr and the process exits non-zero.

Deploy target errors

no deploy target found

The default dist directory does not exist.

Fix it by building first or passing the correct output path:

npm run build
npx wgw-deploy
npx wgw-deploy --dir public

not a file or directory: <path>

The explicit --dir path does not exist or is not a file or directory.

npx wgw-deploy --cwd /path/to/app --dir build

no deployable files in <path>

The target is empty, or every file was ignored. The CLI skips symlinks and ignores common local or sensitive paths, including .git, node_modules, .cache, .turbo, .wrangler, coverage, .env*, database files, private keys, certificates, and SSH-related files.

Choose a static output folder that contains publishable files.

Size and manifest errors

too many files in <path>

The deploy has more than 5,000 files.

file too large: <file>

One file is larger than 10 MiB.

total upload too large: <path>

The combined deploy is larger than the service limit.

request body too large, manifest too large, bad manifest, or empty manifest

These usually mean a custom client or self-hosted integration sent an invalid prepare request. The normal CLI builds the manifest for you.

bad manifest path: <path> or reserved manifest path: <path>

Manifest paths must be safe relative paths for the project. _rev is reserved for pinned revision URLs.

CLI argument errors

unexpected positional argument: <value>

The CLI does not accept positional deploy targets. Use --dir.

npx wgw-deploy --dir dist

missing value for --dir, missing value for --cwd, or missing value for --domain

Pass the required value after the flag.

npx wgw-deploy --cwd /path/to/app --dir build
npx wgw-deploy --domain preview.wgw.lol

unknown option: <flag>

Check the supported options:

npx wgw-deploy --help

API and ownership errors

could not reach the deploy API

The CLI could not connect to the API. Check the network. If you override the API endpoint, check WGW_API_URL.

WGW_API_URL=https://deploy.wgw.lol npx wgw-deploy --dir dist

unsupported API URL: <value>

WGW_API_URL must be an http or https URL.

bad bearer token

The local project state has an invalid API token for the remote project. Use the original local state, or create a fresh project by deploying from a different --cwd plus --dir pair.

project ownership mismatch

The request reached a real project, but the local project hash or anonymous machine fingerprint did not match. Use the same --cwd and --dir that created the project.

npx wgw-deploy --list --json

project expired

Generated projects can expire if they do not have an assigned non-default domain. The deploy command removes stale local state and retries automatically. Delete and domain-delete commands treat expired projects as already deleted.

Domain errors

bad project domain

The hostname is invalid. Do not include https://, paths, ports, spaces, @, or nested WGW labels.

Use:

npx wgw-deploy --domain preview-build
npx wgw-deploy --domain docs.example.com

Do not use:

npx wgw-deploy --domain https://docs.example.com/path

reserved project domain

The WGW subdomain name is reserved. Pick another name.

domain already assigned

The requested WGW subdomain is already serving something. Pick another WGW subdomain.

could not verify domain availability

The API could not check the requested WGW subdomain. Retry later.

Cloudflare Custom Hostname failed: <details>

The external hostname request was rejected by Cloudflare. Check that the hostname is valid and that you can create a CNAME for it.

The expected external DNS target is:

CNAME <your-hostname> -> cname.wgw.lol

missing CLOUDFLARE_ZONE_ID

This is a self-hosting configuration error. External custom domains require CLOUDFLARE_ZONE_ID on the API worker.

Cleanup commands

List tracked projects:

npx wgw-deploy --list
npx wgw-deploy --list --json

Remove a custom domain:

npx wgw-deploy --delete-domain
npx wgw-deploy --delete-domain --json

Delete a project:

npx wgw-deploy --delete
npx wgw-deploy --delete --json