Troubleshooting Subdomain File Hosting with Autoindex on Nginx

Nginx autoindex fails to list files in subdomains primarily because the directive is missing from the specific server block or conflicts with proxy_pass rules. Ensure your configuration explicitly enables directory listing and that the root path points to a valid, readable directory on the filesystem.

Verifying Server Block Configuration

The most common reason for unresponsive autoindex functionality is its absence in the server context handling the subdomain. When you set up a subdomain for file hosting, you must ensure that the Nginx configuration file includes the autoindex on; directive within the correct location block. If this directive is missing, Nginx will return a 403 Forbidden error instead of generating an HTML index of the directory contents. You should open your site’s configuration file, typically located in /etc/nginx/sites-available/ or /etc/nginx/conf.d/, and inspect the server block associated with your subdomain. Look for a location / block that defines the root directory. Inside this block, add the following line:

location / {
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
}

The autoindex_exact_size off; setting displays file sizes in human-readable formats (KB, MB) rather than bytes, which improves usability. The autoindex_localtime on; option ensures that modification times are shown in the server's local timezone rather than UTC. After making these changes, reload Nginx using sudo systemctl reload nginx to apply the new settings without dropping active connections.

Checking Root Directory Permissions

Even with correct directives, autoindex will fail if the Nginx worker process cannot read the files in the target directory. By default, Nginx runs as the www-data user on Debian-based systems or nginx on RHEL-based systems. If the directory containing your files has restrictive permissions, such as 700 owned by root, the web server will be unable to traverse the directory or read the files. To resolve this, verify the ownership and permissions of your document root. You can change the ownership to the Nginx user or a shared group using the chown command. For example:

sudo chown -R www-data:www-data /var/www/subdomain-files

Additionally, ensure that the directory permissions allow reading and execution. A permission setting of 755 for directories and 644 for files is standard and secure for public file hosting. If you are using SELinux, you may also need to set the appropriate context for the directory using semanage fcontext and restore the context with restorecon.

Distinguishing Between Proxy Pass and Static Files

A frequent point of confusion arises when developers mix static file serving with reverse proxy configurations. If your server block contains a proxy_pass directive, Nginx forwards requests to a backend application (like Node.js or Python). In this scenario, autoindex is ignored because Nginx does not serve the files itself; the backend application handles the response. If your goal is to host static files directly via Nginx, remove any proxy_pass lines from the relevant location blocks. Instead, use the root or alias directive to point to the physical directory. For subdomains, it is often cleaner to create a dedicated server block rather than mixing logic in a single configuration file. This approach isolates the file hosting service from other applications, reducing the risk of configuration conflicts. For more details on managing subdomains with different technologies, see How to Get a Subdomain Pointing to a PM2 App on Nginx Ubuntu Server.

Testing and Debugging

After applying the configuration changes, test the setup by accessing the subdomain in a web browser. If you still encounter errors, check the Nginx error log for specific messages. The error log is typically located at /var/log/nginx/error.log. Common errors include "permission denied" for file access or "directory index of ... is forbidden" if the index file is missing and autoindex is disabled. You can also use the nginx -t command to validate the syntax of your configuration files before reloading. This step prevents accidental service outages due to typos in the configuration. If the syntax is valid but the issue persists, clear your browser cache or try accessing the subdomain from a different device to rule out client-side caching issues. For insights on routing traffic for complex setups, refer to Nginx Configuration Issue.

Frequently Asked Questions

Why do I get a 403 Forbidden error even with autoindex on?

This usually indicates that the Nginx user lacks read permissions for the directory or files. Check the ownership and mode of your document root to ensure the web server process can access them.

Can I use autoindex with a reverse proxy?

No, autoindex is a static file serving feature. If you use proxy_pass, the backend application generates the response, so Nginx ignores autoindex directives in that context.

How do I hide specific files from the autoindex listing?

Nginx does not have a built-in directive to exclude files from autoindex. You would need to use a custom index page or a rewrite module to filter specific filenames before they are listed.

Does autoindex work with HTTPS?

Yes, autoindex works perfectly over HTTPS. However, ensure that your SSL certificates are correctly configured and that the certificate is valid for the subdomain you are accessing.

What is the difference between root and alias in this context?

The root directive appends the URI to the specified path, while alias replaces the URI part. For simple file hosting under the same path, root is generally easier to configure and less prone to path mismatch errors.