Skip to content

One app behind Traefik shows 404, 502 or Gateway Timeout

TroubleshootingDeployrr v6.0+CurrentTraefikApp networkingLogsAuthentication

You open https://APP.YOUR_DOMAIN and one app fails. Your other apps behind Traefik still work. This page starts from the error you see and helps you narrow it down.

The browser shows one of these plain pages:

404 page not found
Bad Gateway
Gateway Timeout

Or the app shows 404 page not found, and traefik.log has a line like this. NAME is a login method, such as authelia:

middleware "chain-NAME@file" does not exist

Traefik sends each web address to an app using a small file for that app. The file is named app-NAME.yml and sits in appdata/traefik3/rules/HOSTNAME/ inside your Docker folder. NAME is the app’s name and HOSTNAME is your server’s hostname.

The error tells you which part is wrong:

You see What it means
404 page not found Traefik has no route for the address you typed. The app has no file, the file has a mistake, or Traefik did not load it.
Bad Gateway (502) Traefik has a route, but the app refused the connection or is not at the address in the file.
Gateway Timeout (504) Traefik has a route, but the app did not answer in time.

If Nextcloud shows “Access through untrusted domain”, the page comes from Nextcloud, not Traefik. See Nextcloud says Access through untrusted domain.

To understand how a file like this differs from Docker labels, read UDMS part 18: Docker labels vs the file provider (manual setup, background only; folder names differ from Deployrr).

Open the app without Traefik first. This tells you where to look.

  1. Find the app’s port. Run dps (without the aliases, sudo docker ps -a) and look at the PORTS column for the app. The number on the left is the one you need. The app reference lists the usual ports.
  2. On a device in your home network, open http://SERVER_IP:PORT. Replace SERVER_IP with your server’s local IP address and PORT with the number from step 1. If the app only answers on HTTPS, use https:// and accept the certificate warning.
What you see What it means
The app opens The app works. The problem is between Traefik and the app. Continue with the Fix steps.
The app doesn’t open there either The app itself is failing. Traefik can’t fix that. See A container keeps restarting, is unhealthy or has exited.
The PORTS column is empty for the app The app has no port on your server, so you can’t open it this way. Use the Traefik dashboard below. The login apps are like this. See Apps that use Docker labels.

The Traefik dashboard shows what Traefik loaded. Open http://SERVER_IP:8080 from your home network. This address has no login, so don’t open it to the internet. If port 8080 was taken when you set up Traefik, use the TRAEFIK_PORT value from your .env file instead. Under HTTP > Routers, find the app’s router, for example NAME-rtr@file, or NAME-rtr@docker for the apps that use labels. If it isn’t in the list, Traefik didn’t load a route for the app, which gives a 404. A router with a warning or error shows the reason when you click it.

Work through the steps in order. Stop when the app opens. For a manual-setup version of this checklist, see UDMS part 18: 404 or Cloudflare 502 in a manual Traefik setup (manual setup).

  1. Go to your Docker folder.

    Terminal window
    cdd

    Without the aliases, use cd YOUR_DOCKER_FOLDER. Replace YOUR_DOCKER_FOLDER with the path to your Docker folder.

  2. Load the failing address in your browser, then look at the access log. It records 404, 502 and 504 responses.

    Terminal window
    tail -n 20 logs/$HOSTNAME/traefik/access.log

    Traefik writes this file in batches. Load the page a few times if nothing shows up.

  3. Search the Traefik log for the app’s name. Replace NAME with the app’s name.

    Terminal window
    grep -i NAME logs/$HOSTNAME/traefik/traefik.log | tail -n 20

    Look for lines about a router, a service or a middleware. A line that says a middleware does not exist points to step 5.

For more on these files, see Read the Traefik logs.

  1. List the file for the app.

    Terminal window
    sudo ls appdata/traefik3/rules/$HOSTNAME/app-NAME.yml
  2. If you see No such file or directory, go to The app has no Traefik file below. Then come back to step 3.

  3. If the file is there, continue.

A few apps, such as Traefik itself, Authelia, Authentik, Google OAuth and TinyAuth, have no app-NAME.yml file. They use labels in their file in compose/HOSTNAME/ instead. See Apps that use Docker labels.

  1. Copy the file to your home folder, outside the rules folder.

    Terminal window
    sudo cp appdata/traefik3/rules/$HOSTNAME/app-NAME.yml ~/app-NAME.yml.bak
  2. Show the file.

    Terminal window
    sudo cat appdata/traefik3/rules/$HOSTNAME/app-NAME.yml
  3. Find these lines. Your file may have a few more.

    http:
    routers:
    NAME-rtr:
    rule: "Host(`SUBDOMAIN.{{env "DOMAINNAME_1"}}`)"
    entryPoints:
    - websecure-external
    - websecure-internal
    middlewares:
    - chain-no-auth
    service: NAME-svc
    services:
    NAME-svc:
    loadBalancer:
    servers:
    - url: "http://172.17.0.1:8989"

    What each part does:

    • rule: is the address. SUBDOMAIN must match what you type in the browser. To change it on purpose, see Change the subdomain of an app you already installed.
    • entryPoints: lists where the app can be reached. A line that starts with # is switched off.
    • middlewares: names the login method.
    • url: is where Traefik sends the request: the host, then the app’s port.

    You save changes to this file with sudo nano appdata/traefik3/rules/$HOSTNAME/app-NAME.yml. Traefik picks up a saved change on its own. You don’t need to restart it. To see a file like this written by hand, watch Traefik guide: put an external app behind Traefik with a rules file at 9:41 (manual Docker Compose setup; Deployrr writes the file for you).

4. For a 404: check the address and the file

Section titled “4. For a 404: check the address and the file”
  1. Compare the subdomain on the rule: line with the address in your browser. Fix a typo in either.
  2. Check the rule: line for a missing backtick, quote or bracket. See Open a dashboard at your root domain for how the line works.
  3. If you use Advanced mode, check the entryPoints: lines. An app set to Internal only opens from your home network. An app set to External only opens from the internet. In Advanced mode, an app you install from the Apps menu is Internal only unless you picked otherwise, so its address gives a 404 from outside your home. See Simple vs Advanced Traefik mode.
  4. Check that the file is directly in appdata/traefik3/rules/HOSTNAME/. A file in a subfolder, or one level up in rules/, is not picked up when you save it. See Which files Traefik loads.
  5. Check that no other file uses the same router or service names. See Two files use the same names.
  6. Read the Traefik log again. A mistake in the file, such as bad indentation, shows up there. For common naming slips, see UDMS part 18: typos and misnaming in Traefik files (manual setup).

5. Fix a login method that is not installed

Section titled “5. Fix a login method that is not installed”

The middlewares: list names a login chain. If the chain names a method you have not installed, Traefik drops the route. You then see a 404, and the log says the middleware does not exist.

At install, Deployrr only offers login methods that are running. So this usually happens after you edit the file by hand or remove a login app later.

The chain names are:

Chain Login method
chain-no-auth No Authentication
chain-basic-auth Basic HTTP Auth
chain-authelia Authelia
chain-authentik Authentik
chain-oauth Google OAuth
chain-tinyauth TinyAuth

To see how a chain groups middlewares, watch Traefik middlewares guide: middleware chains at 15:24 (manual Docker Compose setup; Deployrr creates the chains for you).

  1. Open the app’s file and read the chain name under middlewares:.

  2. Check that the method is installed and running.

    Terminal window
    dps

    Without the aliases, run:

    Terminal window
    sudo docker ps -a

    You should see authelia, authentik, oauth or tinyauth with a status that starts with Up.

  3. If it is not installed, install it from the Security menu. Or change the chain to one you have, for example chain-basic-auth. You can do that with Security > Manage Auth (Pro) or by editing the file. See Choose a login method.

  4. Check the spelling of the chain name. It must match one in the table.

Basic HTTP Auth and No Authentication are there once Traefik Preparation is done.

6. For a 502 or Gateway Timeout: check the app and its port

Section titled “6. For a 502 or Gateway Timeout: check the app and its port”
  1. Check that the app is running.

    Terminal window
    dps

    Without the aliases, run sudo docker ps -a. The status must start with Up. If it says Restarting or Exited, see A container keeps restarting, is unhealthy or has exited.

  2. Look at the PORTS column for the app. A value like 0.0.0.0:8989->8989/tcp means the app answers on port 8989 on your server. The number on the left is the one that counts.

  3. Compare that number with the port at the end of the url: line in the app’s file. If they differ, change the number in the file and save it.

    Deployrr writes the port into the file once, when it creates the file. If you change the app’s port later, for example in your .env file, the file keeps the old port. See Port already in use for how to change a port.

  4. Test the address from the file on your server. Replace URL_FROM_THE_FILE with the url: value, for example http://172.17.0.1:8989.

    Terminal window
    curl -sS --max-time 10 -o /dev/null -w "%{http_code}\n" URL_FROM_THE_FILE

    A number such as 200, 301 or 302 means the app answers. If you see Connection refused, the app is not listening there. If it times out after 10 seconds, nothing answers at that address.

  5. If the test works on your server but the app still gives a 502 or a timeout, test the same address from inside the Traefik container. Traefik sends the request from its own Docker network, so a firewall or a name lookup can treat it differently from your server.

    Terminal window
    sudo docker exec traefik wget -q --spider URL_FROM_THE_FILE && echo OK

    OK, or server returned error with an HTTP code such as 401, means Traefik reached the app. For bad address, Connection refused or a timeout, see what each result means in Use a hostname instead of an IP address.

  6. If the app runs on another machine, check that the IP address in the file is that machine’s address. Check that a firewall on it allows your Deployrr server to reach the port.

  7. If the app only answers on HTTPS, the url: line must start with https://. See Put any app behind Traefik with Traefikify.

  8. If the app is slow to start, wait a minute and load the page again.

Deployrr writes an app’s file when you install the app while Traefik is running and the app supports Traefik. These cases leave you without a file:

  • Setup Mode is Local. Local mode doesn’t use Traefik. See Setup Mode: Local or Hybrid.
  • You installed the app while Traefik was not running, for example before Proxy > Traefik > Staging, or while Traefik was stopped. Deployrr does not go back and add files for apps you installed earlier.
  • You added the app yourself in custom.yml. Deployrr does not make a file for it.

To add the file, use Traefikify. It needs a Plus or Pro license.

  1. Find the app’s port. The number on the left in the PORTS column is the one you need.

    Terminal window
    dps

    Without the aliases, run sudo docker ps -a.

  2. In Deployrr, go to Proxy > Traefik > Traefikify.

  3. Enter a name, a subdomain, your server’s local IP address, http and the port from step 1.

  4. Pick a login method and an exposure method.

To see Traefikify in use, watch Deployrr 5 walkthrough: Traefikify an app at 1:04:24 (shows Deployrr v5; menus and steps differ in v6).

See Put any app behind Traefik with Traefikify for every prompt. If Traefik isn’t set up yet, see Set up Traefik.

Each app file has a router name that ends in -rtr and a service name that ends in -svc. These names must be unique across all files in the rules folder. This happens when you copy a file for a second copy of an app and forget to rename them. One of the two apps may then stop working, or its address may open the other app.

  1. Run this from your Docker folder. It prints a name only if more than one file uses it.

    Terminal window
    sudo grep -rhoE "^ +[A-Za-z0-9_-]+-(rtr|svc):" appdata/traefik3/rules/$HOSTNAME/ | sort | uniq -d
  2. If it prints nothing, no names clash.

  3. If it prints a name, find the files that use it. Replace NAME-rtr with the name it printed.

    Terminal window
    sudo grep -rn "NAME-rtr:" appdata/traefik3/rules/$HOSTNAME/
  4. Back up the file you will change, as in step 3 above.

  5. Rename the router and its service in that file. Change both the -rtr and -svc names, and the service: line that points to the service.

See Run a second copy of an app for a full example.

These apps get their Traefik route from labels in their own file in compose/HOSTNAME/, not from a rules file:

App Address File
Traefik dashboard traefik.YOUR_DOMAIN traefik.yml
Authelia authelia.YOUR_DOMAIN authelia.yml
Authentik authentik.YOUR_DOMAIN authentik.yml
Google OAuth oauth.YOUR_DOMAIN oauth.yml
TinyAuth tinyauth.YOUR_DOMAIN tinyauth.yml

If a login app fails, the apps that use its login method can’t open either. Fix the login app first.

  1. Check that the app is running. From your Docker folder, run dps (without the aliases, sudo docker ps -a). The status must start with Up. Traefik only reads labels from a running container.

  2. Check the health in the same status. If it shows (health: starting) or (unhealthy), Traefik skips the app and you get a 404. Authentik can take a minute after a start. If it stays like that, see A container keeps restarting, is unhealthy or has exited.

  3. Check that socket-proxy is running in the same list. Traefik reads labels through Socket Proxy. If it’s stopped, see Socket Proxy.

  4. Read the labels. Replace NAME with the file name from the table, for example authelia.

    Terminal window
    grep traefik compose/$HOSTNAME/NAME.yml
    • The rule=Host(...) label is the address.
    • The middlewares= label names the login chain. The Traefik dashboard uses chain-basic-auth by default. Security > Manage Auth can change it. Authelia, Authentik and TinyAuth use chain-no-auth for their own page, and Google OAuth uses chain-oauth.
    • The loadbalancer.server.port= label is the port inside the container. It isn’t a port on your server, so don’t change it to match .env.
  5. Check that the app is on the traefik_proxy network. Traefik reaches label apps only there.

    Terminal window
    sudo docker inspect -f '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' NAME

    The output must include traefik_proxy.

  6. If you changed a label, Traefik doesn’t see it until you recreate the app. Saving the file is not enough.

    Terminal window
    dcrec NAME

    Without the aliases, run this. Replace YOUR_DOCKER_FOLDER, HOSTNAME and NAME with your own values.

    Terminal window
    sudo docker compose --profile all -f YOUR_DOCKER_FOLDER/docker-compose-HOSTNAME.yml up -d --force-recreate --remove-orphans NAME

    Security > Manage Auth recreates the app for you when it changes a label.

Deployrr starts Traefik so it watches the rules folder for changes. Keep your files directly in appdata/traefik3/rules/HOSTNAME/. Traefik loads files there when it starts, and it picks up a new, changed or deleted file on its own.

To edit these files safely, add your own middleware or restore a file, see Edit Traefik rules files safely.

Changes to files in a subfolder are not picked up until you recreate Traefik. A file one level up, in appdata/traefik3/rules/, is not loaded at all.

A change to Traefik’s own file, compose/HOSTNAME/traefik.yml, is different. Traefik reads it only when you recreate it:

Terminal window
dcrec traefik

Without the aliases, run:

Terminal window
sudo docker compose --profile all -f YOUR_DOCKER_FOLDER/docker-compose-HOSTNAME.yml up -d --force-recreate --remove-orphans traefik

Replace YOUR_DOCKER_FOLDER and HOSTNAME with your own values. Recreating Traefik drops web connections for a few seconds.

  1. Open https://APP.YOUR_DOMAIN in a private browser window. Replace APP and YOUR_DOMAIN with your own values.

  2. You see the app, or the login page of your login method.

  3. Follow the Traefik log while you load the page. No new error lines appear for the app.

    Terminal window
    traefiklogs

    Press Ctrl+C to stop.

If the browser shows a certificate warning instead, see Traefik can’t get a Let’s Encrypt certificate.