Docs/When something breaks

Why a build fails, and what to do

Nearly every failed first deploy is one of five things. Open the log, read the last few lines, and find it below.

Where this lives: Dashboard → Project → Log

Published 0 files

The build worked and the publish step found nothing, which means the output directory is not where your build writes. Run the build on your own machine, see which folder appears, and put that name in the field. The framework presets list the right folder for the common tools.

Install fails on a lockfile

npm ci refuses to run when package-lock.json does not match package.json, and it refuses to run at all when there is no lockfile. Either commit an up-to-date lockfile — run npm install locally and push the result — or change the install command to npm install.

Build works locally, fails here

The sandbox is a clean machine, so anything that only exists on yours is missing. Usually one of: a dependency you installed globally and never added to package.json, a file in .gitignore that the build needs, or a filename whose capitalisation differs — macOS ignores case in filenames and the build machine does not, so import Button from './button' fails there and works at home.

Missing environment variable

The build reads undefined and either crashes or quietly ships a broken page. Check the name is spelled exactly as your code reads it, including the prefix your framework requires — VITE_, NEXT_PUBLIC_, or PUBLIC_ — and remember a variable only reaches a site through a deploy that ran after it was saved.

The build never finishes

The build command has to exit. npm run dev, next dev and vite start a server and stay running forever, so the deploy waits until it times out. The command you want is the one that produces files and stops, usually npm run build.

Nothing appears at the address

If the deploy succeeded and the page is blank, the files published are not the ones you expected. Check that your output directory contains an index.html at its top level, not one folder deeper.