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

Last reviewed by Netlify Support - August, 2023

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 “Options” > “Clear cache and retry deploy” 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. If you are using yarn workspaces or a monorepo please consult the appropriate documentation (linked to in this sentence).
  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.

Another fix is to update your package.json scripts to run in order and wait for one to finish before moving to another.

& as in eleventy & npm run tailwind:build - means run both eleventy and npm run tailwind:build at the same time. I don’t care about which script finishes first just run them.

&& as in eleventy && npm run tailwind:build run eleventy wait for eleventy to finish, then run npm run tailwind:build

I found the answer to my problem here: Postinstall script fails using netlify-lambda to install function dependencies · Issue #227 · netlify/netlify-lambda · GitHub.

It seems using netlify-lambda install in postinstall also triggers this problem. It should be moved to prebuild as a work arround.