BTCPay Server

# Troubleshooting

This guide covers the Docker deployment. For application-level problems, also check the BTCPay Server troubleshooting guide.

# Confirm the Saved Environment

Start a root login shell and verify the deployment paths:

sudo su -
printf 'Base: %s\nCompose: %s\nEnvironment: %s\n' \
  "$BTCPAY_BASE_DIRECTORY" "$BTCPAY_DOCKER_COMPOSE" "$BTCPAY_ENV_FILE"

On Linux, the profile is stored in /etc/profile.d/btcpay-env.sh. If variables are empty, start a new login shell or source that file.

# Check Container State

docker-compose -f "$BTCPAY_DOCKER_COMPOSE" ps
docker-compose -f "$BTCPAY_DOCKER_COMPOSE" config --quiet

The generated configuration should parse without errors. A stopped or restarting service usually has the most useful immediate log output. Do not publish full docker-compose config output without careful redaction; interpolated environment values can include tunnel tokens and add-on passwords.

# Inspect Logs

docker-compose -f "$BTCPAY_DOCKER_COMPOSE" logs --timestamps
docker-compose -f "$BTCPAY_DOCKER_COMPOSE" logs --tail 200 btcpayserver
docker logs --tail 200 nginx

Follow one service while reproducing a problem:

docker-compose -f "$BTCPAY_DOCKER_COMPOSE" logs -f btcpayserver

After an update, inspect the compressed pre-update snapshots described in Updating.

# Check Bitcoin Synchronization

bitcoin-cli.sh getblockchaininfo
bitcoin-cli.sh getnetworkinfo

Compare the reported block height with a current public source. BTCPay Server cannot reliably detect payments until Bitcoin Core and NBXplorer are caught up.

# Check Nginx and HTTPS

Confirm DNS points to this host and ports 80/443 reach it. Then validate Nginx:

docker exec nginx nginx -t
docker logs --tail 200 nginx
btcpay-routes show
curl --show-error --silent --output /dev/null "https://$BTCPAY_HOST/"

When using the bundled automatic HTTPS setup, also inspect its ACME companion:

docker logs --tail 200 letsencrypt-nginx-proxy-companion

Setup can exit successfully even if certificate issuance fails. Check this output for the configured hostname and use the curl result as an independent check that its certificate is valid. Do not bypass certificate validation with curl --insecure.

A 503 response often means Nginx received the request but did not find a route for its hostname. Confirm BTCPAY_HOST, and set REVERSEPROXY_DEFAULT_HOST only when requests with unrecognized hosts should reach BTCPay Server.

If another proxy terminates HTTPS, confirm it preserves the Host and X-Forwarded-Proto headers. See Networking.

# "Your access to BTCPay Server is over an unsecured network"

If HTTPS is terminated by an external reverse proxy, ensure it sends X-Forwarded-Proto: https, then reconfigure BTCPay Server to trust the proxy:

export TRUST_DOWNSTREAM_PROXY="true"
. ./btcpay-setup.sh -i

Only enable this when the BTCPay host's HTTP port is accessible exclusively through the trusted reverse proxy. See External Reverse Proxy.

# Restart the Stack

btcpay-restart.sh

btcpay-up.sh includes a recovery check for an Nginx container that failed during recreation. If Nginx remains down, the command prints its latest logs.

# Collect Diagnostics Before Requesting Help

Include:

  • The exact command and error
  • The selected network, cryptocurrencies, Lightning implementation, and additional fragments
  • docker-compose -f "$BTCPAY_DOCKER_COMPOSE" ps
  • Relevant service logs with secrets and customer information removed
  • Whether DNS, ports, proxies, or firewall rules recently changed
  • The current repository commit from git -C "$BTCPAY_BASE_DIRECTORY/btcpayserver-docker" rev-parse HEAD

Ask deployment questions in the community chat (opens new window). Use the GitHub issue tracker (opens new window) for reproducible defects in this repository.

← Customization →