Last checked: November 2024
So your build failed and you’re unsure where to start to fix it? You’re in the right place! In this guide we’ll walk through the basic steps of how to locate the cause of a build failure and where to go to find solutions.
Locating the cause of the issue
If your build fails on Netlify, the first step in debugging is to ensure it builds locally. Once you confirm the build succeeds locally, you’ll want to check out the Netlify build logs. To find your build logs, go to your Netlify dashboard for your site. On the left, you’ll see a link for Deploys. Clicking that will bring you to a page of deploys - one for every build you’ve created. Clicking on a deploy brings you to the deploy log:
To view the logs in more detail, click on the dropdown where you see the failure, in this case, “Building.” This will allow you to browse the build logs in detail.
A build will fail if it returns a non-zero exit code. This will show up near the end of your logs:
While it may appear at first glance that this exit code is the reason for failure, this exit code is actually a symptom of an error earlier in the log. This exit code doesn’t provide any hints as to what caused the failure.
However, you can find those hints further back in the deploy logs. The logs contain specific messages that indicate why a build has failed. A few lines above this exit code we see a detailed error message that gives us more insight into the cause of this failure:
It’s useful to note that build failures can be incredibly varied and sometimes the reason for the failure won’t be as clear or will take a little investigative work to locate.
Another useful way to locate the cause of the build failure is our new “Why did it fail?” AI feature. This will do the work of digging through the logs and identifying the root cause for you. Take the failed build from above, for example. If I use the “Why did it fail?” button, I see the following explanation:
Finding solutions
So you successfully located the error message that points to the cause of the failure, now how do you fix it?
Sometimes, the error message tells you exactly what to do to solve it:
In this case, updating Node.js to the specified version will solve the issue.
However, other times the error message is confusing or unclear or you don’t know where to even start. In those cases, it’s useful to search our forums for the specific error to see if other people have encountered the same issue. You can also try searching the Netlify Docs. If that doesn’t help, try doing a quick Google search on the error in your log. Oftentimes build errors that appear in your Netlify build have happened elsewhere off of Netlify as well, and finding a solution just takes a little bit of digging. Odds are someone has had the same question as you and likely they have offered a solution, too.
If you still find yourself stuck, create a new forums post referencing the specific error that you’re seeing, as well as steps you’ve taken to resolve the issue, and the name of the site in question.