How to configure HTTP/2 push headers in Nginx

Enable HTTP/2 server push in Nginx to allow the server to proactively send assets like CSS and JavaScript to the client before they are requested. These steps target Nginx 1.24.x running on Linux systems with HTTP/2 enabled. Follow the instructions to configure the http block and reload the service.

Prerequisites

• Nginx version 1.24.x or higher installed on the system.
• HTTP/2 protocol enabled in the server block configuration.
• Root or sudo access to edit the Nginx configuration files.
• A valid domain name pointing to the server.

Step 1: Locate the Nginx configuration file

Identify the main configuration file or the specific site configuration file where the server block is defined. On most distributions, this file is located in /etc/nginx/sites-available/default or /etc/nginx/conf.d/default.conf. You will edit this file to add the push directives.

sudo nano /etc/nginx/sites-available/default

Step 2: Define the push resource

Inside the server block, define the resource you want to push. Use the push directive to specify the URI of the asset. Ensure the asset is served with a long cache lifetime to maximize the benefit of server push. The directive syntax requires the URI path relative to the server root.

location / {
    root /var/www/html;
    index index.html;
    push /static/style.css;
    push /static/app.js;
}

Step 3: Enable HTTP/2 in the server block

Ensure the http2 directive is present in the server block to enable the HTTP/2 protocol. Without HTTP/2, the push headers will not be processed by the client. Place this directive inside the server block, typically near the top of the block.

server {
    listen 443 ssl http2;
    server_name example.com;

    # ... other settings ...

    location / {
        # ... other settings ...
        push /static/style.css;
        push /static/app.js;
    }
}

Step 4: Configure push headers for specific conditions

Optionally, restrict server push to specific conditions using the if directive or limit it to specific paths. For example, you might only push assets on the homepage to avoid pushing resources on dynamic pages. Use the push directive with a condition to ensure the resource is only sent when necessary.

location / {
    root /var/www/html;
    if ($uri = "/") {
        push /static/style.css;
        push /static/app.js;
    }
}

Step 5: Test the Nginx configuration

Before reloading the service, verify the syntax of the configuration file to prevent service interruption. Run the nginx -t command to check for errors. If the output says nginx: configuration file /etc/nginx/nginx.conf test is successful, proceed to reload the configuration.

sudo nginx -t

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

Verify the installation

Access the website using a modern browser that supports HTTP/2 push, such as Chrome or Firefox. Open the browser's Developer Tools, navigate to the Network tab, and select the Initiator or Initiator column to see if the pushed resources appear before the main document is fully loaded. Alternatively, use curl with the -H flag to inspect the response headers for the X-Accel-Redirect or similar indicators, though browser inspection is more direct for push events.

curl -v https://example.com

You will see the request headers in the response, and the pushed resources should appear in the network waterfall view of the browser.

Troubleshooting

If the browser does not show the pushed resources, check the following common errors:

Error: "Pushed resources are not supported by the client"

Ensure the client browser supports HTTP/2 push. Older browsers or those with disabled HTTP/2 will ignore push headers. Verify the browser is up to date and that the http2 protocol is enabled in the connection settings.

Error: "nginx: [emerg] unknown directive "push" in /etc/nginx/sites-available/default:15"

This error indicates that the Nginx version does not support the push directive or the module is not compiled in. Ensure you are running Nginx 1.9.5 or higher. If using a custom build, verify that the http2_module is included during compilation.

Error: "502 Bad Gateway" after reloading Nginx

This usually means the upstream server is unreachable or the configuration syntax is invalid. Run nginx -t again to check for syntax errors. Ensure the upstream backend is running and responding to requests.

Error: "Pushed resource not found"

Verify that the path specified in the push directive exists on the server and is accessible. Check file permissions and ensure the root directive points to the correct directory containing the static assets.