How to troubleshoot deployment failures on Netlify
Quick Answer
First verify your build succeeds locally, then use Netlify's AI 'Why did it fail?' feature on the deploy summary page for instant diagnosis. Review logs for errors like exit status 128, adjust build settings, and retry without cache if needed.
Prerequisites
- Build works locally
- Netlify Owner or Developer access
- Git repository linked
- Basic terminal knowledge
Step-by-Step Instructions
1
Verify build locally
Run your build command in the local terminal, such as
npm run build or yarn build, checking your package.json for the exact script. Ensure it completes without errors and outputs files to the expected directory like dist or build. This isolates if the issue is Netlify-specific.2
Navigate to failed deploy
Log in to
app.netlify.com, select your site, go to the Deploys tab, and click the failed deploy row to open the deploy summary page.3
Use Why did it fail? AI
On the deploy summary page, click the Why did it fail? button for AI analysis of logs and fix suggestions like dependency issues. Enable it first if needed: Team settings > General > AI enablement > Configure > Enabled.
Available on Starter, Pro, Enterprise plans unless disabled by Owner.
4
Review deploy logs
Click Deploy log on the summary page and search for errors. Look for
Exit status 128 (repo permissions), TypeScript errors like 'user id should be a string not a number', or dependency failures. Scroll to the timestamped failure point.5
Check build settings
Go to Site configuration > Build & deploy > Continuous deployment > Build settings. Verify Base directory (e.g.
/client), Build command (e.g. npm ci && npm run build), and Publish directory (e.g. dist/public). Save and trigger new deploy.6
Retry without cache
In Deploys tab, click Retry deploy > Retry without cache to clear
~/.npm and node modules. Match Node version in netlify.toml: [build]
environment = { NODE_VERSION = "20.11.0" } Fixes package version mismatches.
7
Inspect files with Deploy File Explorer
On deploy details page, open Deploy File Explorer to navigate output like a filesystem. Search for files like
index.html, check for missing assets causing 404s, or download ZIP/files to verify publish directory. Use on successful deploys too.
8
Relink repository
For permission errors, go to Project configuration > Build & deploy > Continuous deployment > Repository > Manage repository > Link to a different repository. Check Git provider webhook settings to avoid duplicates.
9
Handle large files
Files over 10 MB fail uploads; host large content externally like YouTube embeds. Large sites with tens of thousands of files may process slowly but shouldn't fail.
10
Match dependency versions
Ensure local package versions match Netlify's by checking dependency management settings. This is the leading cause of build failures.
Test locally with same Node version.
Common Issues & Troubleshooting
Exit status 128
Repo clone permission issue; relink repository and check Git webhook settings.
Package version mismatches
Match local deps to Netlify, use <code>npm ci</code>, set NODE_VERSION in netlify.toml.
Missing files or 404s
Verify publish directory in build settings; use Deploy File Explorer.
Large files over 10 MB
Host externally; avoid embedding large media.
TypeScript/dependency errors
Review logs for specifics like type mismatches; use AI diagnosis.