Deploy

Deployment troubleshooting

Fix deployments that don't start, fail to build, or don't serve what you expect.

Start with the deployment's status and logs on its page in the dashboard to find the stage that failed. To separate a deployment problem from a domain problem, test the deployment's unique URL first.

A deployment didn't start

Check that:

The repository is still connected and the commit was pushed to it.
Easel still has webhook access in your Git provider.
The project isn't paused, which blocks new Production deployments, and the workspace isn't suspended, which blocks all deployments.
The deployment wasn't marked Skipped by Skip unaffected deployments because the push didn't touch the project. See Skipping deployments.

If your Git provider shows the push was delivered but no deployment appeared, contact support with the repository, branch, commit SHA, and delivery time.

A deployment is stuck in Queued

A queued deployment is waiting for a build slot. Check whether the workspace already runs as many builds as its plan allows, and check the Easel status page. See Build queue. You can cancel a queued deployment.

A build failed

Open the build logs and find the first error. Common causes:

Dependency installation failed, or the lockfile is out of date.
The build command, root directory, or detected framework is wrong. See Build configuration.
A variable the build needs is missing for this environment.
The build ran out of memory or time. See Build machines and Limits.
The resolved environment variables are too large. See Limits.

A deployment that shows Canceled after the clone was stopped by an Ignored build step that exited 0, not by a failure.

Reproduce the build locally with the same Node.js version and build command.

A monorepo build works locally but fails on Easel

Check, in order:

The project's root directory.
The install and build commands.
The package manager version and committed lockfile.
Whether shared workspace packages resolve in a clean checkout.
Variables used during install or build.
Skip rules that decided whether to build. See Monorepos.

An environment variable is missing or stale

Check that:

You set it in the right project, under the exact name, with the same capitalization.
It targets the deployment's environment, Preview or Production, and no branch override replaces it for this branch.
You created a new deployment after the change. Existing deployments keep the values they were built with.
It's available when it's read. A public variable, such as NEXT_PUBLIC_ or VITE_, is embedded at build time, so changing it takes a rebuild.

See Environment variables.

It works locally but fails after deploying

A successful build doesn't guarantee the app works at runtime. Check function logs, then look for:

Runtime variables missing for this environment.
Native packages built for your machine instead of Linux.
Import paths whose case doesn't match the file name. Builds run on Linux, where paths are case-sensitive.
Code that relies on the local filesystem. See Filesystem.
Browser APIs called during server rendering.
Connections to external services, and your framework's compatibility.

If the unique URL works but your custom domain doesn't, the problem is in routing, DNS, or HTTPS. See Domain troubleshooting.

The Node.js version is ignored

Set the version in Project settings → Functions → Node.js version. Setting engines.node in package.json alone isn't enough. The setting applies to new deployments, so redeploy after changing it.

A function runs out of memory

Before you move to a larger CPU tier, look for large in-memory buffers, unbounded collections or module-level caches, large responses built in memory, native libraries, and memory leaks. See Function configuration.

A function times out

Use traces and logs to find slow queries or APIs, retry loops, streams that never close, and work that should run after the response. Raise the maximum duration only when the work fits within a request. See Limits and Background work.

A preview URL shows an older version

A unique deployment URL never moves. Branch and pull request URLs move only when a newer deployment is Ready. Check whether the newest deployment is still building, failed, was canceled or skipped, or was created for a different branch or project.

Production still serves the previous deployment

Check whether the new Production deployment:

Is Ready, or still building or failed.
Is Staged, because Promote production builds automatically is off in Project settings → Git. Promote it.
Is Staged because you rolled back, which turns automatic promotion off. See After a rollback.
Was built from the branch you expect to be the production branch.

A custom domain serves the wrong deployment

Custom domains serve only the Current Production deployment, never a Preview deployment. Check that:

The production URL serves the deployment you expect. If it doesn't, see Production still serves the previous deployment.
The domain belongs to this project, and its DNS and HTTPS setup are complete. See Domain troubleshooting.
No redirect sends the request somewhere else, and you aren't seeing a cached response. See CDN troubleshooting.

Workspace, project, and deployment ID or URL
Git branch and commit SHA
Approximate time, and the X-Easel-Id response header for a failing request
Relevant build or runtime logs and steps to reproduce
Whether Preview, Production, or both are affected

Managing Deployments

Inspect, cancel, and spin down Easel deployments.

Overview

Deploy frontend and full-stack frameworks to Easel.