SKILL.md
Diagnose a Hostinger build failure
When to use
- A deploy returned state
failed. - The user reports the live site showing a build or runtime error.
- The user asks "why did my deploy fail?".
Inputs to gather first
- Domain.
- The build
uuid. If the user doesn't have it, callhostinglistJsDeployments(orhostinglistNodeJSBuildsV1) for the domain and filterstatestofailed. - For
hostinggetNodeJSBuildLogsV1you also needusername— get it fromhostinglistWebsitesV1.
Steps
- Fetch the logs:
- hostingshowJsDeploymentLogs with domain + buildUuid for hostingdeployJsApplication builds. - hostinggetNodeJSBuildLogsV1 with username + domain + uuid for archive builds. - Both accept a start line (fromLine / fromline) — page through rather than requesting one enormous response.
- Log content may contain ANSI escape sequences. Strip them before quoting.
- Match against the signatures below, then report the most likely cause and a concrete fix.
Common failure modes
| Signature in logs | Likely cause | Fix |
|---|---|---|
Error: Cannot find module 'X' |
Dependency missing from package.json, or it was only in devDependencies |
Add it to dependencies, rebuild |
npm ERR! ERESOLVE, peer dep |
Dependency resolution conflict | Pin versions, or commit a lockfile so the server installs deterministically |
engine "node" is incompatible, syntax errors in dependency code |
Node version mismatch | Set nodeversion to 18, 20, 22, or 24 on hostingcreateNodeJSBuildFromArchiveV1, or fix engines.node |
sh: vite: not found, build script not found |
Wrong build_script, or the build tool is in devDependencies and wasn't installed |
Override build_script; verify the script name in package.json |
no such file or directory for package.json |
Wrong project root in a monorepo | Set rootdirectory relative to publichtml |
| Build succeeds but the site 404s | Wrong output_directory |
Point output_directory at the real build output, relative to the root directory |
JavaScript heap out of memory |
Build exceeded the memory cap | Reduce the build footprint, or upgrade the plan |
| Wrong package manager resolving deps | Lockfile/manager mismatch | Set package_manager to npm, yarn, or pnpm |
| App builds and starts but gets no traffic | Port hardcoded | Bind to process.env.PORT |
undefined config values at runtime |
Missing environment variables | Environment variables are not settable via the API — the user must add them in hPanel |
Report format
- Cause — one sentence, quoting the exact log line.
- Fix — the concrete code change or the tool call with the specific override.
- Next action — offer to apply it, and wait for confirmation.
Do not
- Do not guess a cause without quoting a log line.
- Do not redeploy automatically — a redeploy overwrites what is live. Propose and wait.
- Do not blame a "framework preset" — Hostinger has no preset parameter. The overrides in
rules/nodejs-deployments.mdcare the real knobs.