[Support Guide] My site deploy fails unless Netlify's build cache is cleared

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

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 “Retry deploy” > “Clear cache and deploy site” within a specific deploy. 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.
  5. You might be running into our failure to handle Yarn workspaces or other monorepo-based development flows in the expected way. This issue on GitHub has some more details.
  6. Fairly rare but worth mentioning: You have a package.json in your repo root, but you are building a subdirectory of your repo and have NOT appropriately set the base directory in your build settings. That can lead to some confusing caching situations since we’ll only sometimes use that package.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.