Bug: Port Forwarding Is Included As Part Of Healthcheck On Initial Start - Dependent Containers Fail

[danieledwardgeorgehitchcock]

Is this urgent?

No

Host OS

Ubuntu 24.04

CPU arch

x86_64

VPN service provider

ProtonVPN

What are you using to run the container

docker-compose

What is the version of Gluetun

Running version latest built on 2026-06-29T11:29:25.299Z (commit 93cc5a4) on Linux 6.8.0-124-generic (x86_64)

What's the problem 🤔

When starting Gluetun with the following Healthcheck (found in docs):

    healthcheck:
      test: ["CMD", "/gluetun-entrypoint", "healthcheck"]
      start_period: 30s
      interval: 15s
      timeout: 5s
      retries: 5

The state of VPN port forwarding appears to be included within the Healthcheck metrics.

This creates a circular problem / race condition if the containers (such as qBittorrent) have dependencies on the Gluetun service being healthy.

Gluetun should have a cooldown period on the Healthcheck endpoint which would allow for the qBittorent service to come up.

Share your logs (at least 10 lines)

07/01/2026, 11:48:21 AM
STDOUT
2026-07-01T11:48:21+01:00 INFO [port forwarding] --2026-07-01 11:48:21--  (try: 2)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:21 AM
STDOUT
2026-07-01T11:48:21+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:21 AM
STDOUT
2026-07-01T11:48:21+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:21 AM
STDOUT
2026-07-01T11:48:21+01:00 INFO [port forwarding]
07/01/2026, 11:48:23 AM
STDOUT
2026-07-01T11:48:23+01:00 INFO [port forwarding] --2026-07-01 11:48:23--  (try: 3)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:23 AM
STDOUT
2026-07-01T11:48:23+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:23 AM
STDOUT
2026-07-01T11:48:23+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:23 AM
STDOUT
2026-07-01T11:48:23+01:00 INFO [port forwarding]
07/01/2026, 11:48:26 AM
STDOUT
2026-07-01T11:48:26+01:00 INFO [port forwarding] --2026-07-01 11:48:26--  (try: 4)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:26 AM
STDOUT
2026-07-01T11:48:26+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:26 AM
STDOUT
2026-07-01T11:48:26+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:26 AM
STDOUT
2026-07-01T11:48:26+01:00 INFO [port forwarding]
07/01/2026, 11:48:30 AM
STDOUT
2026-07-01T11:48:30+01:00 INFO [port forwarding] --2026-07-01 11:48:30--  (try: 5)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:30 AM
STDOUT
2026-07-01T11:48:30+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:30 AM
STDOUT
2026-07-01T11:48:30+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:30 AM
STDOUT
2026-07-01T11:48:30+01:00 INFO [port forwarding]
07/01/2026, 11:48:35 AM
STDOUT
2026-07-01T11:48:35+01:00 INFO [port forwarding] --2026-07-01 11:48:35--  (try: 6)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:35 AM
STDOUT
2026-07-01T11:48:35+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:35 AM
STDOUT
2026-07-01T11:48:35+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:35 AM
STDOUT
2026-07-01T11:48:35+01:00 INFO [port forwarding]
07/01/2026, 11:48:41 AM
STDOUT
2026-07-01T11:48:41+01:00 INFO [port forwarding] --2026-07-01 11:48:41--  (try: 7)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:41 AM
STDOUT
2026-07-01T11:48:41+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:41 AM
STDOUT
2026-07-01T11:48:41+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:41 AM
STDOUT
2026-07-01T11:48:41+01:00 INFO [port forwarding]
07/01/2026, 11:48:48 AM
STDOUT
2026-07-01T11:48:48+01:00 INFO [port forwarding] --2026-07-01 11:48:48--  (try: 8)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:48 AM
STDOUT
2026-07-01T11:48:48+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:48 AM
STDOUT
2026-07-01T11:48:48+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:48 AM
STDOUT
2026-07-01T11:48:48+01:00 INFO [port forwarding]
07/01/2026, 11:48:56 AM
STDOUT
2026-07-01T11:48:56+01:00 INFO [port forwarding] --2026-07-01 11:48:56--  (try: 9)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:48:56 AM
STDOUT
2026-07-01T11:48:56+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:48:56 AM
STDOUT
2026-07-01T11:48:56+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:48:56 AM
STDOUT
2026-07-01T11:48:56+01:00 INFO [port forwarding]
07/01/2026, 11:49:05 AM
STDOUT
2026-07-01T11:49:05+01:00 INFO [port forwarding] --2026-07-01 11:49:05--  (try:10)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:49:05 AM
STDOUT
2026-07-01T11:49:05+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:49:05 AM
STDOUT
2026-07-01T11:49:05+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:49:05 AM
STDOUT
2026-07-01T11:49:05+01:00 INFO [port forwarding]
07/01/2026, 11:49:15 AM
STDOUT
2026-07-01T11:49:15+01:00 INFO [port forwarding] --2026-07-01 11:49:15--  (try:11)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:49:15 AM
STDOUT
2026-07-01T11:49:15+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:49:15 AM
STDOUT
2026-07-01T11:49:15+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:49:15 AM
STDOUT
2026-07-01T11:49:15+01:00 INFO [port forwarding]
07/01/2026, 11:49:25 AM
STDOUT
2026-07-01T11:49:25+01:00 INFO [port forwarding] --2026-07-01 11:49:25--  (try:12)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:49:25 AM
STDOUT
2026-07-01T11:49:25+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:49:25 AM
STDOUT
2026-07-01T11:49:25+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:49:25 AM
STDOUT
2026-07-01T11:49:25+01:00 INFO [port forwarding]
07/01/2026, 11:49:35 AM
STDOUT
2026-07-01T11:49:35+01:00 INFO [port forwarding] --2026-07-01 11:49:35--  (try:13)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:49:35 AM
STDOUT
2026-07-01T11:49:35+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:49:35 AM
STDOUT
2026-07-01T11:49:35+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:49:35 AM
STDOUT
2026-07-01T11:49:35+01:00 INFO [port forwarding]
07/01/2026, 11:49:45 AM
STDOUT
2026-07-01T11:49:45+01:00 INFO [port forwarding] --2026-07-01 11:49:45--  (try:14)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:49:45 AM
STDOUT
2026-07-01T11:49:45+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:49:45 AM
STDOUT
2026-07-01T11:49:45+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:49:45 AM
STDOUT
2026-07-01T11:49:45+01:00 INFO [port forwarding]
07/01/2026, 11:49:55 AM
STDOUT
2026-07-01T11:49:55+01:00 INFO [port forwarding] --2026-07-01 11:49:55--  (try:15)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:49:55 AM
STDOUT
2026-07-01T11:49:55+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:49:55 AM
STDOUT
2026-07-01T11:49:55+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:49:55 AM
STDOUT
2026-07-01T11:49:55+01:00 INFO [port forwarding]
07/01/2026, 11:50:05 AM
STDOUT
2026-07-01T11:50:05+01:00 INFO [port forwarding] --2026-07-01 11:50:05--  (try:16)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:50:05 AM
STDOUT
2026-07-01T11:50:05+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:50:05 AM
STDOUT
2026-07-01T11:50:05+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:50:05 AM
STDOUT
2026-07-01T11:50:05+01:00 INFO [port forwarding]
07/01/2026, 11:50:15 AM
STDOUT
2026-07-01T11:50:15+01:00 INFO [port forwarding] --2026-07-01 11:50:15--  (try:17)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:50:15 AM
STDOUT
2026-07-01T11:50:15+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:50:15 AM
STDOUT
2026-07-01T11:50:15+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:50:15 AM
STDOUT
2026-07-01T11:50:15+01:00 INFO [port forwarding]
07/01/2026, 11:50:25 AM
STDOUT
2026-07-01T11:50:25+01:00 INFO [port forwarding] --2026-07-01 11:50:25--  (try:18)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:50:25 AM
STDOUT
2026-07-01T11:50:25+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:50:25 AM
STDOUT
2026-07-01T11:50:25+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:50:25 AM
STDOUT
2026-07-01T11:50:25+01:00 INFO [port forwarding]
07/01/2026, 11:50:35 AM
STDOUT
2026-07-01T11:50:35+01:00 INFO [port forwarding] --2026-07-01 11:50:35--  (try:19)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:50:35 AM
STDOUT
2026-07-01T11:50:35+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:50:35 AM
STDOUT
2026-07-01T11:50:35+01:00 INFO [port forwarding] Retrying.
07/01/2026, 11:50:35 AM
STDOUT
2026-07-01T11:50:35+01:00 INFO [port forwarding]
07/01/2026, 11:50:45 AM
STDOUT
2026-07-01T11:50:45+01:00 INFO [port forwarding] --2026-07-01 11:50:45--  (try:20)  http://127.0.0.1:7288/api/v2/app/setPreferences
07/01/2026, 11:50:45 AM
STDOUT
2026-07-01T11:50:45+01:00 INFO [port forwarding] Connecting to 127.0.0.1:7288... failed: Connection refused.
07/01/2026, 11:50:45 AM
STDOUT
2026-07-01T11:50:45+01:00 INFO [port forwarding] Giving up.
07/01/2026, 11:50:45 AM
STDOUT
2026-07-01T11:50:45+01:00 INFO [port forwarding]
07/01/2026, 11:50:45 AM
STDOUT

+1
2026-07-01T11:50:45+01:00 ERROR [port forwarding] running up command: exit status 4

Share your configuration

Gluetun:

services:
  gluetun:
    image: ghcr.io/qdm12/gluetun:latest@sha256:b0ee2135e6ba52ad3f102aae9663707cd1c9531485117067a380d3b2b6dd991d
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    networks:
      - vpn
      - reverse-proxy
      - metric
    volumes:
      - type: volume
        source: gluetun-data
        target: /gluetun
      - type: volume
        source: gluetun-ports
        target: /ports
      - type: bind
        source: ./config/authentication.toml
        target: /auth/config.toml
        read_only: true
    healthcheck:
      test: ["CMD", "/gluetun-entrypoint", "healthcheck"]
      start_period: 30s
      interval: 15s
      timeout: 5s
      retries: 5
    depends_on:
      traefik:
        condition: service_healthy
        restart: true
    env_file:
      - path: ./env/.env
        required: true

volumes:
  gluetun-data:
    driver: local
  gluetun-ports:
    driver: local

Env File:

VPN_SERVICE_PROVIDER="protonvpn"
VPN_TYPE="openvpn"
OPENVPN_USER="REDACTED"
OPENVPN_PASSWORD="REDACTED"
SERVER_COUNTRIES="Netherlands,Romania,Switzerland"
VPN_PORT_FORWARDING="on"
VPN_PORT_FORWARDING_PROVIDER="protonvpn"
VPN_PORT_FORWARDING_STATUS_FILE="/ports/protonvpn"
UPDATER_PERIOD="24h"
HTTPPROXY="off"
DNS_UPSTREAM_PLAIN_ADDRESSES="127.0.0.11"
HTTP_CONTROL_SERVER_AUTH_CONFIG_FILEPATH="/auth/config.toml"
UPDATER_PROTONVPN_EMAIL="REDACTED"
UPDATER_PROTONVPN_PASSWORD="REDACTED"
VPN_PORT_FORWARDING_UP_COMMAND=/bin/sh -c 'wget -O- --retry-connrefused --post-data "json={\"listen_port\":$(echo {{PORTS}} | cut -d, -f1),\"random_port\":false,\"upnp\":false}" http://127.0.0.1:7288/api/v2/app/setPreferences 2>&1'
VPN_PORT_FORWARDING_DOWN_COMMAND=/bin/sh -c 'wget -O- --retry-connrefused --post-data "json={\"listen_port\":123}" http://127.0.0.1:7288/api/v2/app/setPreferences 2>&1'




qBittorrent:

services:
  qbittorrent:
    image: qbittorrentofficial/qbittorrent-nox:latest@sha256:a41fbfe983349e2d81baad1d2a40544143c9e0ec1e79493d091554406e0eab1a
    container_name: qbittorrent
    network_mode: service:gluetun
    volumes:
      - type: volume
        source: qbittorrent-config
        target: /config
      - type: volume
        source: qbittorrent-download
        target: /downloads
      - type: bind
        source: /mnt/media/Videos
        target: /videos
      - type: bind
        source: /mnt/media/Music
        target: /music
      - type: tmpfs
        target: /tmp
      - type: bind
        source: ./config/qBittorrent.conf
        target: /config/qBittorrent/config/qBittorrent.conf
        read_only: False
    depends_on:
      gluetun:
        condition: service_healthy
        restart: true
    env_file:
      - path: ./env/.env
        required: true
    labels:
      traefik.enable: true
      traefik.http.services.qbittorrent.loadbalancer.server.port: "7288"
      traefik.http.routers.qbittorrent.service: "qbittorrent"
      traefik.http.routers.qbittorrent.rule: "Host(`qbittorrent.${HOST}`)"
      traefik.http.routers.qbittorrent.entrypoints: "http-secure"
      traefik.http.routers.qbittorrent.tls: true
      traefik.http.routers.qbittorrent.tls.certresolver: "letsencrypt"
      traefik.http.routers.qbittorrent.middlewares: "hsts@file"

volumes:
  qbittorrent-config:
    driver: local
  qbittorrent-download:
    driver: local

[github-actions]

@qdm12 is more or less the only maintainer of this project and works on it in his free time.
Please:

• do not ask for updates, be patient
• 👍 the issue to show your support instead of commenting
  @qdm12 usually checks issues at least once a week, if this is a new urgent bug,
  revert to an older tagged container image

[qdm12]

The state of VPN port forwarding appears to be included within the Healthcheck metrics.

It does not, vpn port forwarding failure does not affect the healthcheck for now. The healthcheck only monitors access to internet (see wiki). Why do you think that?

[sbrocket]

@danieledwardgeorgehitchcock This isn't default behavior you're seeing. That output is from the wget command in your VPN_PORT_FORWARDING_UP_COMMAND. That's what causes gluetun to reach out to qbittorrent.

That said, even though this isn't default behavior the OP is following an example documented on the wiki: VPN_PORT_FORWARDING_UP_COMMAND

It's still not very clear what you're seeing related to the healthcheck though OP. Your logs don't really show the healthcheck restarting the gluetun container too aggressively or anything like that. Is the problem that your qbittorrent container never starts up? That's probably the fault of making qbittorrent depend on gluetun being healthy:

    depends_on:
      gluetun:
        condition: service_healthy
        restart: true

This is incompatible with your VPN_PORT_FORWARDING_UP_COMMAND; you probably want service_started instead. Also, beware that depends_on.restart's behavior is pretty useless for what you seem to be trying to do; it will not restart the qbittorrent container automatically if gluetun becomes unhealthy and then recovers.

Also, beware that using network_mode: service:gluetun on qbittorrent (as I know is the recommended setup) means that you have to restart the qbittorrent container if gluetun restarts, or else it is left in a weird state (e.g. it may only have a loopback interface left).

I tried this approach out recently while debugging my own issues (where gluetun would lose connection and never regain it, and I ended up needing to manually restart it) and depends_on.restart seemed like the right tool here to me too, but in my testing it did not seem to restart dependent containers reliably? Specifically for me it did not seem to restart dependent containers when I manually restarted the dependency (gluetun). I'm not 100% confident there, I wasn't exhaustive, but I would suggest testing it yourself to be sure it actually does what you expect.

[github-actions]

Closed issues are NOT monitored, so commenting here will likely NOT be seen.
If you think this is still unresolved and have more information to bring, please either
re-open this issue or create another issue.

❤️😠 temporarily help the Gluetun community and fight the AI slop scam website gluetun[dot]com by setting BORINGPOLL_GLUETUNCOM=on on the latest image.
See the option in the wiki for more information

This is an automated comment setup because @qdm12 is the sole maintainer of this project
which became too popular to monitor closed issues.