Trouble activating NGINX for reverse proxy to my BTCPay Server

Support and Troubleshooting
1

I’m following this guide to set up an NGINX Reverse Proxy for Umbrel/BTCPay Server by @jorijn, but am unable to get past Step 5 (testing/reloading NGINX). Hoping someone with more experience with shell commands can help me…

I believe Steps 1-4 were successful… I received no errors when installing NGINX and Certbot or when editing the NGINX config file.

However, in Step 5 when I run:

sudo nginx -t

I get:

2025/06/04 16:53:06 [warn] 3286936#3286936: the "http2_max_field_size" directive is obsolete, use the "large_client_header_buffers" directive instead in /etc/nginx/sites-enabled/btcpay:7
2025/06/04 16:53:06 [warn] 3286936#3286936: the "http2_max_header_size" directive is obsolete, use the "large_client_header_buffers" directive instead in /etc/nginx/sites-enabled/btcpay:8
2025/06/04 16:53:06 [emerg] 3286936#3286936: invalid URL prefix in /etc/nginx/sites-enabled/btcpay:22
nginx: configuration file /etc/nginx/nginx.conf test failed

Therefore I’m also unable to reload NGINX to apply the new configuration. I only get:

nginx.service is not active, cannot reload.

For reference, my NGINX configuration file (/etc/nginx/sites-available/btcpay) contains the following (note: I’ve hidden my domain and my node’s IP address):

# Set higher buffer sizes for BTCPay Server potentially large headers/requests
proxy_buffer_size          128k;
proxy_buffers              4 256k;
proxy_busy_buffers_size    256k;
client_header_buffer_size 500k;
large_client_header_buffers 4 500k;
http2_max_field_size       500k;
http2_max_header_size      500k;

# Required for WebSocket support (used by BTCPay)
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    # IMPORTANT: Change this to your domain
    server_name btcpay.XXXXXXXX.com;

    location / {
        # Forward requests to the internal BTCPay Server app
        proxy_pass [http://XXX.XXX.X.XXX:3003](http://XXX.XXX.X.XXX:3003);

        # Set headers to pass correct information to BTCPay
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # Listen on the internal port we forwarded earlier (for HTTP)
    listen 40080;
    listen [::]:40080; # Also listen on IPv6

    # SSL configuration will be added here by Certbot later
}

Any help would be greatly appreciated!

2

UPDATE!!

So I asked Perplexity if it could solve this issue and it did! This is a testament to the power of AI. See below for my prompt and the full transcript/solution…

Can you solve the issue described on this page… Trouble activating NGINX for reverse proxy to my BTCPay Server

Absolutely, let’s walk through and solve the issues described in your NGINX configuration for your BTCPay Server reverse proxy. Here’s a breakdown of the errors and how to fix them:

1. Obsolete Directives

Warnings:

  • the “http2_max_field_size” directive is obsolete, use the “large_client_header_buffers” directive instead
  • the “http2_max_header_size” directive is obsolete, use the “large_client_header_buffers” directive instead

Solution:
Remove these two lines from your config:

text

http2_max_field_size 500k;
http2_max_header_size 500k;

You already have:

text

large_client_header_buffers 4 500k;

That’s the correct directive for modern NGINX.

2. Invalid URL Prefix

Error:

  • invalid URL prefix in /etc/nginx/sites-enabled/btcpay:22

This usually means your proxy_pass line is malformed. In your config, you have:

text

proxy_pass [http://XXX.XXX.X.XXX:3003](http://XXX.XXX.X.XXX:3003);

This is not valid NGINX syntax. The square brackets and Markdown-style link are not allowed.

Solution:
Change it to:

text

proxy_pass http://XXX.XXX.X.XXX:3003;

Replace XXX.XXX.X.XXX with your actual internal IP address.

3. Placement of listen Directives

Your listen directives are inside the location block. They must be inside the server block, not inside location.

Solution:
Move these lines:

text

listen 40080;
listen [::]:40080;

So your config should look like:

text

server {
    server_name btcpay.XXXXXXXX.com;

    listen 40080;
    listen [::]:40080;

    location / {
        proxy_pass http://XXX.XXX.X.XXX:3003;
        # ... rest of your proxy_set_header lines ...
    }
    # ... SSL config, etc ...
}

4. Complete Example (Fixed)

Here’s how your /etc/nginx/sites-available/btcpay should look (replace the placeholders as needed):

text

# Set higher buffer sizes for BTCPay Server potentially large headers/requests
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
client_header_buffer_size 500k;
large_client_header_buffers 4 500k;

# Required for WebSocket support (used by BTCPay)
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    server_name btcpay.XXXXXXXX.com;

    listen 40080;
    listen [::]:40080;

    location / {
        proxy_pass http://XXX.XXX.X.XXX:3003;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket headers
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }

    # SSL configuration will be added here by Certbot later
}

5. Test and Reload

Now, test your config:

bash

sudo nginx -t

If it says the configuration is OK, reload:

bash

sudo systemctl reload nginx

If nginx is not running, start it:

bash

sudo systemctl start nginx

Summary of Fixes

  • Remove obsolete directives (http2_max_field_size, http2_max_header_size)
  • Fix the proxy_pass line (no Markdown or brackets)
  • Move listen directives into the server block
  • Test and reload NGINX

Lastly, NGINX was not previously started which is why it couldn’t be reloaded. So if you get " nginx.service is not active, cannot reload." just type:

sudo systemctl start nginx