Troubleshooting

Use this page when a deploy is up but the site, cache, or firewall does not behave as expected. For framework and build limits, see Frameworks and limits.

Custom domain does not go live

1. Confirm the DNS records match what Project settings → Custom Domains shows (CNAME for subdomains, A for apex).
2. Wait for DNS propagation. Some providers finish in a few minutes; others take longer.
3. Check domain status in the dashboard. It must leave pending DNS before TLS can finish.
4. Open the hostname over https:// after status shows live.

See Custom domains for the full setup flow.

First HTTPS request fails after pointing DNS

The first request after DNS points at Easel can fail until the certificate is ready. Wait a short time and retry. Later requests use the provisioned certificate. Details: Encryption.

Preview URL works but custom domain does not

Custom domains serve production only. Confirm you pushed to the production branch and that production is healthy on the generated production URL first. See Environments.

Unexpected cache MISS or BYPASS

Check the X-Easel-Cache response header. Time to live (TTL) is how long a response may stay cached:

Easel does not invent a default edge TTL when Cache-Control is missing. Dynamic pages stay uncached until you set eligible headers. See Caching.

Content stays stale after you invalidate

1. Confirm you expired the same tag string you wrote (Cache-Tag, Runtime Cache tags, or Next cacheTag / revalidateTag).
2. For CDN-only objects, confirm the response included Cache-Tag (or x-next-cache-tags / surrogate-key) when it was stored.
3. For Runtime Cache, call expireTag (or delete the key) and verify RUNTIME_CACHE_* env is present on the deployment.
4. For Next.js ISR, use revalidatePath / revalidateTag and fetch the page again; the first request after expiry may regenerate.

See Invalidate and revalidate cached content and Runtime Cache.

Visitors see 403 or a challenge page

1. Open Project settings → Custom WAF rules and look for Deny or Challenge rules that match the path, IP, or headers in use.
2. Check whether Attack challenge mode is on for the project.
3. Use a Log action first when testing new rules so you can observe matches without blocking users.
4. Confirm X-Easel-Firewall-Action and X-Easel-Firewall-Rule-Id on the response when present.

See Custom Web Application Firewall (WAF) rules and WAF and attack challenge.

Site returns 503 with x-easel-serve-denied

1. Read the x-easel-serve-denied header (or response body).
2. If the code is PROJECT_PAUSED, an Owner or Admin can turn off Pause production in Project settings. Preview URLs should still work. See Pause and resume a project.
3. If the code is WORKSPACE_SUSPENDED, the whole workspace is blocked until the platform clears suspension. See Workspace is suspended.
4. Wait up to 30s after resume or unsuspend for the edge manifest cache to expire, then retry.

Environment variable missing at runtime

1. Confirm the variable targets the right environment (production vs preview).
2. Remember changes apply to new deployments only. Redeploy after edits.
3. For a single preview branch, check whether a branch override is set.

See Environment variables.

Still stuck

Include the deployment URL, approximate time, and X-Easel-Id response header when you contact support. That id correlates the request in edge logs. See System headers.