When a build fails, HCode reads the build log and, if it recognises the problem, tells you what went wrong and how to fix it. This page lists every build problem it recognises, with the exact summary it shows.
Where to find the message
Open the project's Deployments tab and select the failed deployment. Under What went wrong you see a label for the kind of problem, such as "Dependency lockfile mismatch", the summary, and the steps to fix it. Technical details holds the raw error, and the build log loads below.
For a project's first deploy, the overview shows the same summary with links to the next steps.
If HCode doesn't recognise the problem, a first deploy says "The first deployment failed before your app could start. The build log of the failed deploy has the details." In the build log, look for the first error; later ones usually follow from it.
Getting the fix to HCode
How you rebuild depends on the project's source:
- GitHub: commit and push the fix. The push starts a deploy if the HCode GitHub App is installed on the repository; otherwise, deploy again. See Deploy from GitHub.
- Zip upload: change your local copy, zip it and upload it again with Redeploy with new zip. See Deploy from a zip file.
- A change under Settings: save, then deploy again.
Branch not found
Shown as "Source branch not found". The summary names the branch, for example "This repository has no branch main."
The project names a branch the repository doesn't have. A common cause is a repository whose default branch is master while the project uses main, or a branch that was renamed or deleted. Change Branch under Settings to one the repository has, then deploy again.
Lockfile out of sync
Shown as "Dependency lockfile mismatch". HCode installs dependencies from your lockfile without changing it, so a lockfile that doesn't match package.json stops the build. See Automatic builds.
| Summary | Fix |
|---|---|
| "Your pnpm lockfile is out of sync with the current project config." | Run pnpm install --no-frozen-lockfile locally and commit pnpm-lock.yaml. In a workspace, commit the lockfile from the repository root |
| "Your npm lockfile is out of sync with package.json." | Run npm install locally and commit package-lock.json |
| "Your Yarn lockfile is out of sync with package.json." | Run yarn install locally and commit yarn.lock |
Conflicting dependency versions
Shown as "Dependency peer conflict".
| Summary | Fix |
|---|---|
| "Your project has conflicting dependency versions, so the install cannot be resolved safely." | Line up the package versions locally so the install succeeds, and commit the updated lockfile |
| "Your project has pnpm peer dependency conflicts that need to be resolved locally first." | Fix the versions locally, run pnpm install, and commit the lockfile |
If your project relies on npm's older, looser peer resolution, set Install command under Settings to:
npm install --legacy-peer-deps
HCode only reports this when the install itself failed. A peer dependency warning followed by a different failure is not the cause.
Missing package script
Shown as "Missing package script".
| Summary | Fix |
|---|---|
| "Your project does not define a build script, but HCode tried to run one." | Add a build script to package.json, or set Build command to the command your app uses |
| "Your project is missing the package script that HCode tried to run." | A start, preview or dev script is missing. Add it, or change Start command (optional) |
"Your project has no lint script, but the build or start command runs it." |
Add the named script to package.json, or change the command under Settings |
Node.js or package manager version
Shown as "Unsupported runtime engine". The summary is "Your project requires a different Node.js or package-manager version than the build environment is using."
The engines field in package.json doesn't match the version the build used. Set the version you need in .nvmrc, .node-version or engines, or with Runtime version (optional) under Settings. See Runtime versions.
If HCode chose the Node version for you from an open engines range such as >=18, the details say so: "We built with Node 22 because your package.json allows it". When that is the only clue, the summary is "The build failed on Node 22, the version we chose from your package.json's engines range." Pick another version the same way.
Runtime version not available
Shown as "Runtime version unavailable". The summary names the version, such as "The build could not install Python 3.15." or "The build could not install Node 26.11."
No released build of that version exists yet for the build machine. A version without its patch number only matches releases that are more than 14 days old, so a brand-new minor or major fails. Name a released version in full, such as 3.14.0 rather than 3.14, in your version file (.python-version, .nvmrc), or set it with Runtime version (optional) if the project has no version file. A version file takes precedence over the setting.
Java version
Shown as "Java version mismatch". Automatic builds install Java 21 unless the project asks for another version.
| Summary | Fix |
|---|---|
| "The build could not find Java where JAVA_HOME points." | Remove any JAVA_HOME environment variable you set; HCode sets it to the Java it installs |
| "Your Gradle build asks for a Java version that the build does not have." | Set the version your toolchain needs with Runtime version (optional), choosing Java |
| "Your project needs a different Java version than the build used." | Same: set the version your project builds with, for example 17 |
Database not reachable during the build
Shown as "Build database unreachable".
| Summary | Fix |
|---|---|
| "The build tried to connect to your HCode database, but HCode databases can't be reached while your app is being built." | Move migrations and database checks out of the build and into the start command |
| "The build couldn't reach your database server." | For an outside database, check the host name and that it accepts connections from outside its own network. If the build doesn't need it, move the database step to the start command |
For example, a start command of npx prisma migrate deploy && npm start runs migrations when the app starts. For Umami, the details explain its own SKIP_DB_CHECK=1 switch.
Missing environment variable
Shown as "Missing build environment".
| Summary | Fix |
|---|---|
| "The build is missing one or more required environment variables or config values." | Add the variables the build needs under Environment variables |
| "The build needs the environment variable SECRET_KEY, and it isn't set." | Add the named variable, or read it with a fallback, such as os.environ.get("SECRET_KEY"), if only the running app needs it |
| "Your Next.js config failed to load during the build" | A variable your next.config reads isn't set. Add it |
Project environment variables reach automatic builds. A Dockerfile build doesn't get them, so pass what it needs as build arguments.
Import or file not found
Shown as "Frontend import resolution". The summary is "The frontend build could not resolve one of your imports or file paths."
- Check that every imported file exists in the repository. Files that were never committed, or that
.gitignoreleaves out, are not in the build. - Check the capitals in file names. The build server treats
File.jsandfile.jsas different files, even if your computer doesn't. - In a monorepo, make sure the workspace packages the app imports are committed too.
Framework config errors
Shown as "Framework configuration error".
| Summary | Fix |
|---|---|
| "Your Next.js configuration is invalid or failed to load during build." | Check that next.config.js or next.config.mjs loads in production mode, with no invalid options or missing plugins |
| "Your Astro configuration failed to load during build." | Check astro.config.mjs or astro.config.ts, the integrations it uses, and the variables it reads |
| "Your Vite configuration failed to load during build." | Check vite.config.*, its plugins and aliases, and any app code it imports |
Dockerfile not found
Shown as "Dockerfile missing". The summary names the path, for example "Deployment failed: build mode is dockerfile but Dockerfile was not found in source". The path is relative to the project's root directory.
Commit a Dockerfile at that path, or change Dockerfile path or Build type under Settings. See Dockerfile builds.
The same heading covers two other path problems:
- "Deployment failed: the Docker context path" followed by the path and "is not a folder in the root directory": the context path is relative to the root directory, and
.means the root directory itself. Fix Docker context path under Advanced Dockerfile options. - A message saying the root directory, context path or Dockerfile path "leads outside the repository through a symbolic link": point the setting at a real folder or file in the repository, not a link that goes outside it.
Build took too long
A build that runs past your plan's maximum build time is stopped, and the deployment's error says "build exceeded max duration of" followed by the limit. See Build minutes for the limit, and look in the build log for the step that was still running.
Publishing the image failed
Shown as "Registry publish error". Your app built, and the failure happened while HCode stored the image:
- "HCode could not reach the container registry while publishing the built image."
- "HCode built the image, but the registry rejected the push."
- "HCode lost the connection while publishing the built image to the registry."
This is usually a problem on HCode's side, not in your code. Deploy again in a few minutes, and email [email protected] if it keeps happening.