Fix a failed build on DployHub

When a build fails, nothing breaks for your visitors: the version that is already running keeps serving traffic, and the deploy is simply marked failed. This guide walks through the build errors you are most likely to see, what causes each one, and the exact change that fixes it.

Find the real error first

Open your app, go to the Deployments tab and click the failed deploy. The full build log streams there, along with who triggered it, the commit and how long it ran. If you have alerts turned on, the "Deploy failed" alert also links you straight to it. Scroll to the first red line, not the last one: later errors are usually knock-on effects of the first.

"We couldn't recognise this project"

Symptom: the build stops almost immediately with "We couldn't recognise this project. Add a Dockerfile, a package.json (Node), a requirements.txt (Python) or an index.html (static site) to the repository root (or set the root folder)."

Cause: auto-detection looks only in the root folder, in this order: Dockerfile, package.json, requirements.txt / pyproject.toml / Pipfile, then index.html. If your app lives in a subfolder, such as apps/web in a monorepo, none of those files are at the root.

1. 1

   Open Settings

   Go to the app and open its Settings.

2. 2

   Set the root folder

   Put the path to your app in "Folder with your app", for example apps/web or backend.

3. 3

   Deploy again

   Click Deploy. Detection now runs inside that folder.

"We could not tell how to start your app"

Symptom: a Node.js build fails with "We could not tell how to start your app. Add a "start" script to package.json, or set a start command".

Cause: there is no start script, no recognised framework, and none of the usual entry files (server.js, index.js, app.js, src/index.js, src/server.js, or the main field) exist. The fix is to add a start script:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

Alternatively, type the command into "Start command" in Settings. See build settings for every field you can override.

Install and build command errors

If the log shows your own build command failing, the problem is in your project, and it should fail the same way on your machine. Common causes:

• Lockfile out of sync. With a package-lock.json we run npm ci, which refuses a lockfile that does not match package.json. Run npm install locally and commit the updated lockfile.
• Missing build-time variables. Front-end frameworks often read variables during the build. Add them in the environment variables tab, then deploy again.
• Dev dependencies needed at build time. Check that tools your build uses (TypeScript, Vite, bundlers) are listed in package.json.
• Python packages missing. Make sure every import is in requirements.txt or pyproject.toml.

# Reproduce the build locally before pushing
npm ci && npm run build
# or for Python
pip install -r requirements.txt

Clone, image and timeout errors

• Cannot clone a private repository: connect your GitHub account and create the app from the GitHub source. A public Git URL only works for public repos. See connect GitHub.
• Clone timeout: cloning has a 5 minute limit. Very large repos (committed videos, datasets, node_modules) should drop those files.
• Docker image cannot be pulled: the image must be public and include a tag, for example nginx:1.27-alpine. Check the name and tag on the registry.
• Build timeout: a build can run for up to 30 minutes. Cache-heavy steps, huge installs or running full test suites in the build command can hit this. Move tests to CI and trim the build.

Build passed but the deploy still failed

If the build log ends successfully and the failure appears during release, the image built fine but your app did not start or did not answer. That is covered in app not answering. Still stuck after these checks? Raise a ticket and attach the failed deployment.