Sometimes things don’t go as expected when deploying a website. If you see a 404 on your site, that means the page or resource couldn’t be found.
There are many possible causes, and the absence of something can be tricky debug if you don’t know where to look. Here are some things you can do to find the cause and fix it.
Debugging Tips
Check the error code
If you see a mostly white screen with 404: NOT_FOUND along with a Code and and ID then you can click the blue info box below the error details to find an explanation of the error and some tips to help you solve it.
The error code’s documentation explains the scenarios in which that problem may occur. It also has a set of troubleshooting steps specific to that problem.
Check that the deployment exists
It’s a good idea to check the deployment URL for typos or incorrect paths. This is especially true when accessing specific deployments using Generated URLs which contain a unique hash.
You should review the deployment list from your project dashboard to make sure that (1) the deployment was successful, (2) the deployment was not deleted, and (3) the URL you’re visiting is the correct one for that deployment.
If the deployment exists, review the deployment logs for issues that might have caused the deployment to be unavailable. If there are uncaught errors in a function or component, those could bubble up and cause you to see a 404 error. In this case a try/catch statement can help.
Check the deployment output
The build output might be different from what you expect. You can check it by navigating to the deployment’s details page on your project dashboard. From there, you can go over to the Source tab to check both the Source and Output for that deployment.
Make sure the file your framework uses as the homepage is present. For many projects this should be an index.html file at the root level of the deployment output.
Be careful of capitalization. If the project has a capitalized Index.html you should change it to lowercase index.html and try a new deployment with that change.
If the project uses a traditionally server-side framework, such as Express, you should make sure to put the index.js file in a /api directory so it will be deployed as a serverless function. In that case the path to the first page of your site would look like my-website.com/api which can be altered to use the root path / using rewrites. More specific Express project patterns and troubleshooting tips are covered in https://community.vercel.com/t/express-101-everything-about-deploying-your-express-app-on-vercel/4870.
Check the project configuration
If you find that the build output doesn’t match what you expect, the difference may have been caused by build settings or other project configuration. You can use the CLI to test a build on your local computer with the vercel build command. That can help you test configuration changes without creating a new deployment for each change.
If you’re using a framework, such as Next.js, then you can usually rely on the corresponding Framework Preset in the project’s Build and Development Settings. If any of the commands have overrides, that could be the source of the problem.
The Output Directory is often overlooked but can have a big effect on the deployment. Only the contents of this directory are statically served as part of your deployment, so it’s important that the correct value is used for this setting.
Check the Build and Development Settings and Root Directory carefully to make sure they’re correct for your project.
If the project is part of a monorepo, you’ll also want to check that the root directory is set correctly. An incorrect root directory value would definitely cause unexpected deployment output.
Configuration files within a project are also good to check. If the project uses a vercel.json file for configuration, such as setting path rewrites or scheduling cron jobs, it’s possible that something in the config file caused the 404.
Some frameworks or packages use their own routing method that requires all requests to go through one specific path. This is often seen with SPA projects, Express projects, and other projects using similar architecture. You can solve it using rewrites to direct traffic through the router.
{ "rewrites": [{"source": "/(.*)", "destination": "/"}] }{ "rewrites": [{ "source": "/(.*)", "destination": "/api" }] }Many frameworks use their own configuration files to set redirects, rewrites, runtimes, and other values. It’s worth checking the documentation for your framework to verify that the repo is configured correctly for serverless deployment with Vercel.
Check the domain configuration
If something is wrong with the domain configuration, that could cause a 404 error.
You can check the domain settings within project settings to make sure the domain is added to the project and it has a verified Valid Configuration status. Any detectable invalid configuration will be flagged with a description of what is missing.
Sometimes the solution to a domain configuration issue is not obvious. The domain troubleshooting doc describes domain, DNS, and SSL debugging steps.
Check your access role and permissions
If you're on a team with multiple people, you may have run into a permissions issue. Check that you are allowed to access the deployment by your role and project settings.
If your team uses Trusted IPs to restrict deployment access, then you’ll get a 404 error if you attempt to visit from an IP address that is not specifically allowed.
You should ask the team owner to check your access group and the project’s deployment protection settings to help you get the deployment access you need.
Practical Applications
- Someone reached out about a 404 error on the homepage of their static site.
- We looked into the deployment output and found that the deployment was successful and pages were available, but there was no
index.htmlin the output. Paths likeexample.com/aboutwere working fine, butexample.com/was returning a 404. - The homepage
/path worked as expected after switching the name ofmain.htmltoindex.htmlwith a new deployment. - A community member asked for help with a 404 error. The code was
DEPLOYMENT_NOT_FOUNDso we determined that either the URL was wrong or the deployment was deleted. - Upon reviewing the deployment list and checking with their team, it was discovered that another team member had deleted the deployment. Switching to the URL of a more recent deployment allowed them to continue their work.