Troubleshooting

If you run into any issues with your static site, check the following for tips and solutions for common errors.

403 error

If the deployment of your site completes without error, but you see a 403 error when trying to visit the site in your browser, here are a few things to check:

1. If your site depends on a build step, is the Build command (Settings > Basic details) filled in and correct?
2. Is the Publish directory correct?
3. Are your file permissions* correct? We generally recommend the following permissions for static sites:
   • Directories: 755
   • Files: 644

*File permissions control who can:

• Read: See the contents of a file or view files in a directory.
• Write: Modify a file, or add or delete files in a directory.
• Execute: Run a file and/or execute it as a script, or access a directory and perform functions and commands.

Each file and directory has its own set of file permissions, shown as a 3-digit number. Each number indicates the permission level for each category (read, write, and execute) shown above.

404 error

If the deployment of your site completes without error, but you see a 404 error when trying to visit the site in your browser, there are a few things to check:

1. If your site depends on a build step, is the Build command (Settings > Basic details) filled in and correct?
2. Is the Publish directory correct?
3. Is your repository compatible with Static Site Hosting? It should contain either:
   1. A static site framework that uses Node.js for the build step.
   2. Or static files, such as HTML, CSS, and Javascript, that do not require a build step (leave the Build command blank).

The Build command tells our system how to assemble your site, and the Publish directory is the subdirectory where the finished site files live, relative to the root of your repository. It’s crucial to fill out these fields correctly if your site depends on a build step. This will ensure your site is built and served as you intend. If the Build command is left blank, the system may indicate the deployment is complete, but it will only upload the unbuilt contents of your repository.

Incorrect node version

If you enter a build command for your site, you can select the Node version to use. If you select the incorrect version, the deployment will fail, and there will be an error in the deployment logs that indicates a different Node.js version is needed, similar to this:

"Build project": error [email protected]: The engine "node" is incompatible with this module. Expected version "16.14.0". Got "16.20.0"

Check your static site’s settings, change the Node version as needed, and manually deploy the site again (click Deploy now on the Deployments page).

Unable to determine package manager

If an issue occurs with the build command or configuration file, you may see the following error:

Error: Unable to determine package manager

This error usually occurs due to an incorrect build command or a missing or incorrectly configured package.json file. Here are a couple of things to check:

1. 1. Is the Build command (Settings > Basic details) filled in and correct?
   2. Is the package.json file in your git repository?
   3. Is the package.json file configured correctly, including any conflicting Node version? For instance, you may have chosen Node version 18.16.0 when you added the static site, but in the package.json file, you may have set the Node version to something different, like the following example:
      Copy

      "engines": {
      "node": ">=20.0.0"
      },