Help for owners
My Netlify site will not build or says I used up my allowance
Short answer
A failed Netlify build leaves your live site as it was. Netlify's guide names the usual causes: versions that differ from your computer, missing tools, package conflicts, the CI setting turning warnings into errors, a stale cache and file names whose capitals differ. Read the deploy log first, then try again without cache.
Does this sound like your situation?
- The latest deploy on Netlify shows Failed and my change is not live.
- It builds on my developer's computer but not on Netlify.
- A deploy that worked before now fails with no change from me.
- I received a notice about my plan's usage.
- The log mentions npm, peer dependencies, or exit status 128.
Why does this happen?
Netlify builds in a different environment
Netlify calls a mismatch between the project and the build environment the leading cause of build failure. Its advice is to confirm that the build works locally and that the package versions Netlify uses match yours.
Confirmed by docs.netlify.com
Warnings become errors
Netlify sets CI to true during builds, and some libraries then treat warnings as errors, so a build can fail on a warning that does not fail locally.
Confirmed by docs.netlify.comTechnical detail: A build that passes locally fails on Netlify because of warnings
Package conflicts
Netlify describes npm peer dependency conflicts, which can show as Could not resolve dependency, and says the NPM_FLAGS setting can be used as a workaround.
Confirmed by docs.netlify.com
A stale cache or case-sensitive file names
Netlify says a failed build can be retried without cache, and that its build filesystem is case-sensitive while Windows and macOS usually are not, so a path can work locally and fail there.
Confirmed by docs.netlify.comTechnical detail: Module not found on Vercel but the build passes on my machine
The plan's credits ran short
Netlify's credit-based plans meter usage in credits. The Free plan has a monthly allowance with no auto recharge option, and Personal and Pro plans offer auto recharge. Netlify states that production deploys cost credits while deploy previews, branch deploys and failed deploys are not metered by credits.
Confirmed by docs.netlify.com
What can I do about it today?
- Check that the live site opensA failed deploy does not replace the working one. Open the site to be sure.
- Open the failed deploy and read the logCopy the first error and the lines around it for your developer.
- Use Retry deploy without cache onceNetlify offers it for a failed build. It is safe and does not change your code.
- Note what changed since the last good deployPackages, settings, new files or a changed link to the repository. Give your developer the date of the last success.
- Look at the plan usage pageCheck whether your plan's allowance is used up and what your plan allows. Do not turn on auto recharge until you know what it costs on your plan.
- Do not delete the site or change the domainDeleting a site can take the live address down and loses its settings.
When should I bring someone in?
- Your live content cannot be updated and the log means nothing to you.
- You are unsure whether the account is within its usage allowance.
- The same error returns after a retry.
How do I handle it?
- Read the log from the topI find the first failing step: install, build or publish, and the exact line.
- Match the environmentI build locally with the same Node and package versions Netlify uses and compare.
- Fix the causePackage conflicts, case-sensitive paths and warnings treated as errors are fixed in the code, and I avoid blanket overrides unless justified.
- Check usage before blaming codeI look at the usage page to see if the problem is plan credit rather than the build.
- Pin versions and write it downNode and package versions are fixed so a future update does not break the build silently.
The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.
What do owners ask about this?
Is my site down when a build fails?
No. The last successful deploy stays live until a new one succeeds.
Are failed builds charged?
Netlify's credit page states that failed deploys are not metered by credits. Check your own plan's page, as plans differ.
Are build minutes still a limit?
The credit-based pricing page I read does not list build minutes as a metered unit, but older plans may differ, so check your account's usage page.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.
For your developer: the technical fixes
The build passes with npm run build on your machine and fails on NetlifyA build that passes locally fails on Netlify because of warningsModule not found: Can't resolveModule not found on Vercel but the build passes on my machinenpm ERR! code EUNSUPPORTEDPROTOCOLnpm install fails with EUNSUPPORTEDPROTOCOLFATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memoryFATAL ERROR: heap out of memory during a webpack or npm build