Fix Nginx Basic Auth 404 Not Found

If you’ve enabled basic authentication in Nginx and now get a 404 Not Found instead of a password prompt, the problem is almost always a misconfigured location block or a missing auth_basic directive in the right context. This guide walks you through the exact steps to diagnose and fix it, so your protected directory prompts for credentials and loads correctly.

What You’ll Need

• Access to your server’s terminal (SSH) with sudo privileges
• The path to your Nginx configuration file (usually /etc/nginx/nginx.conf or a site file in /etc/nginx/sites-available/)
• A text editor like nano or vim
• Your password file (e.g., /etc/nginx/.htpasswd) already created with htpasswd or similar

Step-by-Step

1. Identify the configuration file – List your enabled sites with ls /etc/nginx/sites-enabled/. Open the relevant file, often default or your domain’s config, with sudo nano /etc/nginx/sites-enabled/your-site.
2. Check where the 404 originates – A 404 with basic auth usually means Nginx is not even processing the auth_basic directive; it’s falling through to a default location that doesn’t exist. Look for any location / or location /path blocks that might be overriding yours.
3. Place auth directives correctly – The auth_basic and auth_basic_user_file must be inside the location block that handles the URL you’re protecting. For example, to protect the whole site, put them inside location / { ... }. For a subdirectory, use location /admin { ... }.
4. Verify the password file path – Ensure the auth_basic_user_file points to an existing file. Test with sudo ls -l /etc/nginx/.htpasswd. If the file is missing, create it with sudo htpasswd -c /etc/nginx/.htpasswd username (install apache2-utils if needed).
5. Check for conflicting location blocks – Nginx uses the most specific prefix match. If you have location /admin and also location ~ \.php$ that matches, the PHP block might take precedence, bypassing auth. Use location ^~ /admin to force prefix matching and ignore regex blocks.
6. Test the configuration – Run sudo nginx -t to check for syntax errors. If it says “syntax is ok,” reload with sudo systemctl reload nginx.
7. Clear your browser cache – Sometimes the 404 is cached. Try an incognito window or hard refresh (Ctrl+Shift+R).
8. Check file permissions – The password file must be readable by the Nginx worker process (usually user www-data). Run sudo chown www-data:www-data /etc/nginx/.htpasswd and sudo chmod 640 /etc/nginx/.htpasswd.

Common Mistakes

• Putting auth in the wrong context – Placing auth_basic inside server { } instead of location { } can cause it to be ignored or applied unexpectedly.
• Using a relative path for the user file – Always use an absolute path like /etc/nginx/.htpasswd. Relative paths are interpreted relative to the Nginx prefix, not your current directory.
• Forgetting to reload after changes – Editing the config without reloading means the old settings remain active.
• Password file with wrong format – The file must contain lines like username:hashedpassword. If you used plain text, Nginx will fail to authenticate, but that usually gives a 500, not 404.
• Location block with a trailing slash mismatch – If you protect location /admin but the URL is /admin/, Nginx may treat them differently. Use location /admin/ or location ^~ /admin.

Tips

• Use location ^~ /protected to make Nginx skip regex checks for that path, avoiding conflicts with PHP or other handlers.
• If you want to protect only certain files, use a regex like location ~ ^/files/.*\.pdf$ and put auth inside.
• Test with curl -I http://yourdomain.com/protected – you should see 401 Authorization Required instead of 404.
• Consider using auth_basic "Restricted Area"; to set a custom message in the login prompt.
• Keep the password file outside the web root (e.g., /etc/nginx/) to prevent it being downloaded.

Troubleshooting

If you still get a 404 after following the steps:

• Check the error log – Run sudo tail -f /var/log/nginx/error.log and try accessing the URL. Look for “directory index of … is forbidden” or “open() … failed (2: No such file or directory)”.
• Verify the document root – The 404 might be because the actual file or directory doesn’t exist. Ensure the protected path has an index file (like index.html) or a valid script.
• Try a minimal test – Create a temporary location /test { auth_basic ...; root /var/www/html; } and see if that prompts. If it does, the issue is in your original location.
• Check for try_files – If your location has try_files $uri $uri/ =404, it might be returning 404 before auth is evaluated. Remove or adjust it.
• Look for duplicate server blocks – A second server block for the same domain might be catching the request. Use sudo nginx -T to see all loaded configs.

Frequently Asked Questions

Why does basic auth work on one path but not another?

Because each location block is independent. You must add auth_basic and auth_basic_user_file to every location you want protected, or use a location / block and then include auth in nested blocks.

Can I protect the entire site except one file?

Yes. Put auth in location /, then add a more specific location for the public file (e.g., location = /public.html { auth_basic off; }). The exact match takes precedence.

What if I get a 500 Internal Server Error instead?

That usually means the password file is unreadable or malformed. Check permissions and that each line is in the correct user:hash format. Use htpasswd to regenerate.

How do I create the password file on Ubuntu?

Install apache2-utils with sudo apt install apache2-utils, then run sudo htpasswd -c /etc/nginx/.htpasswd username. For additional users, omit the -c flag.

Does the order of directives matter?

No, within a block the order doesn’t matter, but the location matching order does. Prefix locations are checked first, then regex in order of appearance. Use ^~ to skip regex.

Why does the 404 appear only after entering credentials?

That means auth succeeded, but the requested file doesn’t exist. Check your root and index directives inside that location. The path is relative to the root, not the server’s filesystem root.

Related

• Cheaper JBL Flip 7 Alternatives: 12 Speakers to Check
• Political Robocalls Consent Rules for US Phone Users
• Hostinger AI Builder: Rename a Page & Update Site