Title: Troubleshooting
Author: liranadia
Published: September 22, 2026

---

 1. [Infrastructure](https://docs.wpvip.com/infrastructure/)
 2. [Edge servers](https://docs.wpvip.com/infrastructure/edge-servers/)
 3. [Edge Workers](https://docs.wpvip.com/infrastructure/edge-servers/edge-workers/)
 4. Troubleshooting

#  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](https://docs.wpvip.com/vip-cli/troubleshooting/).

Last updated: September 22, 2026