---
title: Troubleshooting
description: Common wgw-deploy CLI and domain errors with direct fixes.
---

# 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:

```bash
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.

```bash
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`.

```bash
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.

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

### `unknown option: <flag>`

Check the supported options:

```bash
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`.

```bash
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.

```bash
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:

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

Do not use:

```bash
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:

```text
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:

```bash
npx wgw-deploy --list
npx wgw-deploy --list --json
```

Remove a custom domain:

```bash
npx wgw-deploy --delete-domain
npx wgw-deploy --delete-domain --json
```

Delete a project:

```bash
npx wgw-deploy --delete
npx wgw-deploy --delete --json
```