Last reviewed by Netlify Support - October, 2024
Netlify builds are highly configurable, but you may encounter some common build problem scenarios, which we describe in depth in these two articles:
- [Support Guide] Debugging Netlify site builds
- [Support Guide] Frequently encountered problems during builds
However, there is an edge case that isn’t mentioned that deserves special treatment: Your build fails every time, UNLESS you manually click “Trigger deploy” > “Clear cache and deploy site” on the deploy listings page or “Options” > “Clear cache and retry deploy” within a specific deploy. This likely indicates another root cause, for example:
- You have committed
node_modulesto your repo which is like committing your kitchen sink. Maybe the dishes are all in there - but they might be dirty and unusable by us a second time. This article has more details about why this is an antipattern (to say that a different way: don’t do it!). - Your dependencies have binary components, which need to be rebuilt for some reason. For instance, if the version of Node.js we use to build changes, any binary modules built against the old version are unlikely to work with the new version - BUT we also may not rebuild them if they are cached already!
- We key off seeing
package.jsonORyarn.lockso having both is an antipattern - we won’t run both for you automatically (see the logic we use in the build script for more details). - You manually manipulate your
node_modulesdirectory in some way during install - and that can corrupt the node module cache which we store and attempt to reuse. This is not generally regarded as a good practice and should be avoided for optimal results in our continuous deployment environment. - If you are using yarn workspaces or a monorepo please consult the appropriate documentation (linked to in this sentence).
- Fairly rare but worth mentioning: You have a
package.jsonin your repo root, but you are building a subdirectory of your repo and have NOT appropriately set thebasedirectory in your build settings. That can lead to some confusing caching situations since we’ll only sometimes use thatpackage.json(when there is nocache).
If you are still having issues and neither the articles linked at the top, nor these tips are applicable, let us know by posting a new topic, describing your specific situation in detail.