Named locations (@) in Nginx - Commands & Configuration

Introduction

Sometimes in nginx, you want to jump to a specific part of your configuration to handle requests differently. Named locations let you create these special spots to send requests internally without changing the URL.

When you want to handle errors or redirects internally without telling the user.

When you need to reuse a block of configuration for different request paths.

When you want to process requests differently based on conditions but keep URLs clean.

When you want to avoid repeating the same configuration in multiple places.

When you want to create a fallback handler for certain requests.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location / {
        # Try to serve file, if not found, go to named location @fallback
        try_files $uri $uri/ @fallback;
    }

    location @fallback {
        # This named location handles requests when files are missing
        proxy_pass http://backend_server;
    }

    location /images/ {
        # Directly serve images
        root /var/www/html;
    }
}

The location / block tries to serve files normally. If the file is not found, it internally redirects to the named location @fallback. The @fallback location proxies the request to a backend server. This setup helps handle missing files gracefully without changing the URL seen by the user.

The location /images/ block serves image files directly from the server.

Commands

Check the nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request for a missing file to test if nginx internally redirects to the named location and proxies correctly.

Terminal

curl -I http://example.com/missingfile.html

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Connection: keep-alive

Key Concept

Named locations let nginx internally redirect requests to special handlers without changing the URL seen by the user.

Common Mistakes

Using named locations with a leading slash like /@fallback instead of @fallback.

Nginx treats named locations starting with @ as special internal locations; adding a slash makes it a normal location and breaks the internal redirect.

Always define and refer to named locations with the @ symbol and no leading slash, like @fallback.

Not testing nginx configuration with 'nginx -t' before reload.

Syntax errors can cause nginx to fail to reload, leading to downtime.

Always run 'sudo nginx -t' to verify configuration syntax before reloading.

Summary

Named locations start with @ and define internal jump points in nginx configuration.

Use try_files or error_page directives to redirect requests internally to named locations.

Always test configuration syntax with 'nginx -t' before reloading nginx to apply changes.