Troubleshooting

Compiler missing or project not found

The compiler is installed within the worker project, and project discovery requires edge-workers.json.

1. Change to the project directory or provide --path.
2. Run npm install if dependencies are missing.
3. Rebuild the selected worker before validation or deployment.

Worker enabled but expected behavior absent

The deployed scope, exported phases, and cache path determine whether the relevant handler runs.

1. Inspect the target environment with edge-workers get <name>.
2. Confirm that the worker is active and the request matches its stored location.
3. Check that the intended phase entrypoint is exported and its handler is implemented.
4. For origin phases, test a request that reaches the origin rather than relying only on cache hits.

Unknown import reported at validate or deploy

An error of the form unknown import: ... has not been defined means the compiled worker references a host function that the edge runtime does not provide. Known causes include:

• process.hrtime(), which compiles to an env::performance.now import.
• AssemblyScript’s standard-library crypto.getRandomValues(), which compiles to an env::crypto.getRandomValuesN import. Import getRandomValues from the SDK instead.
• A host function that the SDK declares but the server does not yet provide.

Use only host functions exported by the SDK. Browser-style standard-library bindings are not available at the edge, and a worker that imports one fails validation rather than failing at request time.

Body value is null

Bodies are not buffered unless the corresponding phase body marker is exported. Add the marker only if the handler needs the body, then rebuild and redeploy. The read-only response.request.body remains null regardless of markers.

KV value missing or counter reset

The key may be absent, evicted, or read with a method for the wrong value type. Return a fallback for missing bytes/text, and expect an absent counter to read as zero. Keep byte and counter keys separate. Do not treat a successful write as a guarantee of permanent retention.

KV counter operation throws

Counter operations reject a key that holds bytes. Use a separate counter key, or deliberately delete the existing value before changing its type. Deleting removes the stored data.

Deployment or enablement failed

A bulk deployment can leave earlier workers changed. Read the completed, failed, and not-attempted names, then inspect their remote state before retrying.

If an enable request fails or times out, the final active state is unknown. The upload may have succeeded and activation may have taken effect. Verify with get or list before deciding whether to redeploy, disable, or take another action. The CLI does not automatically retry, roll back, disable, or delete the affected worker.

Command unavailable or access denied

Confirm that the installed release includes edge-workers, that the intended application and environment are targeted, and that the authenticated account has the required access. For general authentication and installation issues, consult Troubleshooting VIP-CLI.