Troubleshooting
Trace a failing request, find the page for your symptom, and read Easel error codes.
Start here when something on Easel doesn't behave as expected. Find which layer answered the request first, then go to that section's troubleshooting page. Change one setting at a time.
Trace a failing request
-
Identify the deployment. Note the URL, deployment ID, environment, and commit. Reproduce against the deployment's own URL. If that URL works but your domain doesn't, the problem is domain assignment, DNS, or HTTPS, not your build.
-
Capture the request ID. Every response carries an
X-Easel-Idheader. Search for it in Logs or witheasel logs --request-id <id>to open the request's logs, cache result, firewall decision, and trace. -
Find which layer answered. Request details show whether the request was blocked or challenged, redirected or rewritten, served from cache, served as a static file, or routed to a function. See Requests.
-
Inspect the function. For dynamic requests, check the function's logs, errors, duration, memory, cold start, region, and trace spans. See Function observability.
-
Compare environments. When Preview works and Production doesn't, the difference is usually environment variables, domains, credentials, cache state, or build settings.
Find your symptom
| Symptom | Go to |
|---|---|
| A deployment didn't start, failed to build, or is stuck | Deployment troubleshooting |
| A deployment is Ready but returns errors, or production serves an old version | Deployment troubleshooting |
| An environment variable is missing at runtime | Deployment troubleshooting |
| A domain is stuck on DNS, or HTTPS doesn't work | Domain troubleshooting |
| A redirect loops, or some visitors see the old site | Domain troubleshooting |
| A response isn't cached, or content stays stale after a purge | CDN troubleshooting |
| A static file 404s, or a header or rewrite is missing | CDN troubleshooting |
| A valid request is blocked or challenged | Security troubleshooting |
| A request, log, or trace is missing from Observability | Observability troubleshooting |
| A response is slow | A response is slow |
The site returns 503 with x-easel-serve-denied | Error codes |
A response is slow
Open the request's details and find where the time went: cache, function start, function execution, or a downstream database or API. Then use the Easel lever that fits:
- Serve it from the CDN. Static output skips function execution. For
dynamic responses that can be shared, set cache headers and confirm
X-Easel-CacheshowsHIT. See Caching. - Cache data, not just responses. Use Runtime Cache for query results and expensive computations reused across requests.
- Keep data close to the function. Place your database near the function region, and reuse clients across requests. Functions handle overlapping requests, so don't keep request state in module-level variables. See Regions and Function runtime.
- Speed up builds with lockfiles and monorepo build settings. See Build configuration.
Compare preview deployments on the same route before and after a change.
Error codes
Easel generates these responses itself, not your app.
| Status | Header or body | Meaning |
|---|---|---|
403 | X-Easel-Firewall-Action | A firewall rule denied the request. X-Easel-Firewall-Rule-Id names the rule. See Firewall. |
413 | The request body is too large. Your function doesn't run. See Limits. | |
429 | Challenge page | Attack challenge mode challenged a client that hasn't passed verification yet. |
502 | The function crashed, returned an invalid response, or an external rewrite target failed. Check the function's logs. | |
503 | x-easel-serve-denied: PROJECT_PAUSED | The project is paused. Production returns 503; preview deployments keep working. |
503 | x-easel-serve-denied: WORKSPACE_SUSPENDED | The workspace is suspended. Every project and preview returns 503, and new deployments are blocked. |
The x-easel-serve-denied code is also the response body.
To resume a paused project or deal with a suspended workspace, see Deployment troubleshooting.
Contact support
Send:
- Workspace, project, deployment ID, and URL
- The
X-Easel-Idrequest ID and the exact UTC time - Route, HTTP method, and expected versus actual behavior
- Reproduction steps and relevant logs, with secrets removed
A request ID identifies one request; it doesn't describe the failure, so include the error message too.