[Common Issue]: My site deploy fails unless Netlify's build cache is cleared

Netlify builds are highly configurable, but you may encounter some common build problems scenarios, which we describe in depth in these two articles:

However, there is another edge case that isn’t mentioned that deserves special treatment: Your build fails every time, UNLESS you use the “clear build cache” option from our UI’s trigger or retry deploy buttons (on the deploy listings page, or a failed deploy logs page, respectively). This likely indicates another root cause, for example:

  1. You have committed node_modules to 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!).
  2. 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!)
  3. We key off seeing package.json OR yarn.lock so 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).
  4. You manually manipulate your node_modules directory 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 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.