nginx: [emerg] "upstream" directive is not allowed here in /etc/nginx/sites-enabled/wiki.[site].com:48

nginx: [emerg] "upstream" directive is not allowed here in /etc/nginx/sites-enabled/wiki.[site].com:48

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

The upstream Directive Location Trap in Nginx Configuration

The error message nginx: [emerg] "upstream" directive is not allowed here is one of the most common configuration failures when deploying MediaWiki or similar PHP applications. It appears frequently because it stems from a fundamental misunderstanding of how Nginx parses its configuration blocks, not necessarily a syntax error in the lines immediately preceding the failure.

In the scenario you are facing, the configuration file loads successfully on one server but fails on another despite identical versions and content. This discrepancy almost always points to a structural issue within the nginx.conf master context or a specific http {} block definition that differs between the two environments, rather than the specific sites-enabled snippet itself.

Context Matters: Where upstream Lives

In Nginx, directives have strict scoping rules. The upstream block is designed to define a pool of backend servers for load balancing or proxying. Consequently, it must reside inside an http {} block. It cannot exist in a server {} block, a location {} block, or at the top level of the main configuration file.

Your provided vhost file contains this directive:

upstream php5-fpm-sock {
    server unix:/var/run/php5-fpm.sock;
}

Visually, this looks correct because it is technically inside a server {} block in your snippet. However, the error occurs because that specific server block is likely not nested correctly within an http {} block in the active configuration context on the failing server.

The Hidden Culprit: Global vs. Local Configuration

Nginx processes files hierarchically. If you are using a standard setup where /etc/nginx/nginx.conf includes your site configs via an include statement, the structure usually looks like this:

# /etc/nginx/nginx.conf
http {
    # global settings
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # include sites enabled here
    include /etc/nginx/sites-enabled/*;
}

If your sites-enabled directory contains a file that inadvertently defines an upstream block outside of the expected http context, or if there is a stray upstream block defined in the main /etc/nginx/nginx.conf itself, Nginx will throw this error.

On the working server, you might have accidentally placed the upstream block inside the server block but somehow got away with it (perhaps due to a different include order or an older directive allowance that was tightened in your version), whereas on the new server, the strict parsing rules caught the violation immediately. However, the most likely cause for the specific error "not allowed here" is that the upstream directive was placed directly inside the server block without being wrapped in an http context, or—more subtly—the server block itself is defined at a level where upstream is forbidden.

Fixing the Configuration Structure

To resolve this, you must ensure the upstream block is moved to the appropriate scope. The cleanest approach is to define the upstream pool in the main configuration file (/etc/nginx/nginx.conf) or inside an http {} block that includes your site configs, rather than inside the specific server block for MediaWiki.

Here is how you should restructure the definition:

  1. Open /etc/nginx/nginx.conf.
  2. Locate the http { } block.
  3. Move the upstream php5-fpm-sock { ... } definition into that block, alongside other global settings like fastcgi_buffer_size.
  4. Remove the duplicate upstream definition from your /etc/nginx/sites-enabled/wiki.[site].work file.

Your site configuration should only contain directives relevant to routing and handling requests for that specific domain:

server {
    listen [::]:443 ssl;
    listen 443 ssl;
    
    server_name wiki.[site].work;
    root /var/www/wiki.[site].work;
    index index.php;
    autoindex off;
    
    # SSL configuration managed by Certbot
    ssl_certificate /etc/letsencrypt/live/[site].work/cert.pem;
    ssl_certificate_key /etc/letsencrypt/live/[site].work/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    
    client_max_body_size 5m;
    client_body_timeout 60;

    location / {
        index index.php5;
        rewrite ^/([^?]*)(?:\?(.*))? /index.php5?title=$1&$2 last;
    }
    
    location ~ \.php5?$ {
        try_files $uri =404;
        include fastcgi_params;
        
        # Ensure the socket path is correct for your specific PHP version
        fastcgi_pass php5-fpm-sock; 
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_intercept_errors on;
        fastcgi_param HTTPS on;
    }

    location ~ \.php?$ {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_pass php5-fpm-sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_intercept_errors on;
        fastcgi_param HTTPS on;
    }
}

In this corrected version, the upstream block is removed from the file. It should now exist in your main nginx.conf under the http context, defined once for all servers to use.

Verification Steps

Before restarting Nginx, always validate the configuration syntax:

sudo nginx -t

If this command returns syntax is ok and test is successful, you can proceed with reloading the service:

sudo systemctl reload nginx

A common pitfall when copying configurations between servers is assuming that relative paths or variable names are interchangeable without checking their context. Ensure that the socket path /var/run/php5-fpm.sock matches exactly what your PHP-FPM process is actually listening on. Sometimes, the socket file might be named differently (e.g., php8.0-fpm.sock) depending on your system's default PHP version, which would cause a connection error even after fixing the directive location.

If you are deploying MediaWiki specifically, remember that the application expects a specific set of headers and timeouts. The client_max_body_size 5m setting in your example is quite low for modern installations; consider increasing this if you plan to upload images or PDFs to the wiki. While not the cause of the current error, adjusting it now prevents future "413 Request Entity Too Large" issues.

By respecting Nginx's directive scoping rules and ensuring global resources like upstream pools are defined in the correct context, you eliminate ambiguity and ensure consistent behavior across your infrastructure.

Our network