How To Fix Nginx 404 Not Found Errors?

Profile picture of Arjan Schouten, author of the blog post.
Author Arjan Schouten

Last updated:

Nginx returns an HTTP 404 NOT FOUND error when it cannot find the requested resource. How should you handle Nginx 404 Not Found errors?

How to fix an HTTP 404 error in Nginx?

To be able to fix an HTTP 404 error in Nginx it is important to look at the Nginx error log:

[error] 31#31: *1 "/etc/nginx/html/index.html" is not found (2: No such file or directory), client: 172.17.0.1, server: , request: "GET / HTTP/1.1", host: "localhost:8080"

Check the path to the file. If it doesn't exist, either move the files to that directory or change your Nginx config to point to the right directory.

If the file exists, one of the following issues can cause the 404 error:

  1. Incorrect file permissions
  2. Filename case sensitivity
  3. Wrong root directory in nginx.conf
  4. No matching location directive in nginx.conf
  5. You use root instead of alias (or vice-versa)

1. Incorrect file permissions

Nginx returns a 404 error if it has no permission to read the requested file. If the files are stored in /etc/nginx/html/mywebsite, check that Nginx user (usually you name this user www-data or nginx) has read permissions.

ls -l /etc/nginx/html/mywebsite

To check if the Nginx user can access one of your html files use:

su <nginx-user> -s /bin/bash -c 'if [ -r <path-to-html-file> ]; then echo "Readable"; else echo "Invalid permissions"; fi'

Depending on your situation, change ownership of the files or adjust the permissions such that the Nginx user has permission to read the file.

2. Filename case sensitivity

An easy to overlook issue is case sensitivity. Double check your filenames if they have the correct casing!

3. Wrong root directory in nginx.conf

A simple Nginx configuration file might look like this:

/etc/nginx/nginx.conf
events {
    worker_connections  1024;
}

http {
    index index.html index.htm;

    server {
        listen       80;

        root /usr/share/nginx/html; # Pay attention to this

        location / {
        }
    }
}

The root directive tells Nginx in which directory it must look for files to serve to the client. Make sure the directory exists and contains the files you want to serve.

4. No matching location directive in nginx.conf

Location directives specify configuration that applies when a URL matches a specific pattern. This is used for example to match a context path or file extension. Let's look at an nginx.conf:

/etc/nginx/nginx.conf
events {
    worker_connections  1024;
}

http {
    index    index.html index.htm;

    server {
        listen       80;

        location /context-path {
            root /usr/share/nginx/html;
        }
    }
}

Suppose there is a file index.html in /usr/share/nginx/html. If you now request the https://[server-url]/index.html, you will get a 404 Not Found error.

To fix this you can either:

  1. add a location directive or
  2. move the root directive from location to the server directive.

5. Use of root instead of alias (or vice-versa)

Suppose the files we want to serve are in /usr/share/nginx/html/. We want to serve them at http:localhost:8080/context-path/.

In this case, you might want to use alias over root:

/etc/nginx/nginx.conf
events {
    worker_connections  1024;
}

http {
    index    index.html;

    server {
        listen       80;

        location /context-path {
            alias /usr/share/nginx/html/; # Don't use root here
        }
    }
}

The difference between alias and root is that:

  1. root takes the full context-path (/context-path) and puts that after the root. Nginx will look for files in: /usr/share/nginx/html/context-path/
  2. alias takes the part after the location directive and puts that after the root. Nginx will look for files in: /usr/share/nginx/html/

How to prevent 404 Not Found for Nginx?

Test your website with a broken link checker. A broken link test that sends you notifications can help detect 404 Not Found errors early.

Test your website now with the free broken link checker:

Share this article

Was this article helpful?
Thanks for your feedback!

We are sorry to hear that you are not satisfied with the content on this page.

Checkout the ExcellentWebCheck services

ExcellentWebCheck's goal is to improve the online user experience. The tools of ExcellentWebCheck help to detect and improve usability problems on your website.