One app behind Traefik shows 404, 502 or Gateway Timeout
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.
Symptoms
Section titled “Symptoms”The browser shows one of these plain pages:
404 page not foundBad GatewayGateway TimeoutOr 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 existTraefik 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).
Is it the app or Traefik?
Section titled “Is it the app or Traefik?”Open the app without Traefik first. This tells you where to look.
- Find the app’s port. Run
dps(without the aliases,sudo docker ps -a) and look at thePORTScolumn for the app. The number on the left is the one you need. The app reference lists the usual ports. - On a device in your home network, open
http://SERVER_IP:PORT. ReplaceSERVER_IPwith your server’s local IP address andPORTwith the number from step 1. If the app only answers on HTTPS, usehttps://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. Read the Traefik logs
Section titled “1. Read the Traefik logs”-
Go to your Docker folder.
Terminal window cddWithout the aliases, use
cd YOUR_DOCKER_FOLDER. ReplaceYOUR_DOCKER_FOLDERwith the path to your Docker folder. -
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.logTraefik writes this file in batches. Load the page a few times if nothing shows up.
-
Search the Traefik log for the app’s name. Replace
NAMEwith the app’s name.Terminal window grep -i NAME logs/$HOSTNAME/traefik/traefik.log | tail -n 20Look 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.
2. Check that the app has a Traefik file
Section titled “2. Check that the app has a Traefik file”-
List the file for the app.
Terminal window sudo ls appdata/traefik3/rules/$HOSTNAME/app-NAME.yml -
If you see
No such file or directory, go to The app has no Traefik file below. Then come back to step 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.
3. Back up and read the file
Section titled “3. Back up and read the file”-
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 -
Show the file.
Terminal window sudo cat appdata/traefik3/rules/$HOSTNAME/app-NAME.yml -
Find these lines. Your file may have a few more.
http:routers:NAME-rtr:rule: "Host(`SUBDOMAIN.{{env "DOMAINNAME_1"}}`)"entryPoints:- websecure-external- websecure-internalmiddlewares:- chain-no-authservice: NAME-svcservices:NAME-svc:loadBalancer:servers:- url: "http://172.17.0.1:8989"What each part does:
rule:is the address.SUBDOMAINmust 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”- Compare the subdomain on the
rule:line with the address in your browser. Fix a typo in either. - Check the
rule:line for a missing backtick, quote or bracket. See Open a dashboard at your root domain for how the line works. - 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. - Check that the file is directly in
appdata/traefik3/rules/HOSTNAME/. A file in a subfolder, or one level up inrules/, is not picked up when you save it. See Which files Traefik loads. - Check that no other file uses the same router or service names. See Two files use the same names.
- 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).
-
Open the app’s file and read the chain name under
middlewares:. -
Check that the method is installed and running.
Terminal window dpsWithout the aliases, run:
Terminal window sudo docker ps -aYou should see
authelia,authentik,oauthortinyauthwith a status that starts withUp. -
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. -
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”-
Check that the app is running.
Terminal window dpsWithout the aliases, run
sudo docker ps -a. The status must start withUp. If it saysRestartingorExited, see A container keeps restarting, is unhealthy or has exited. -
Look at the
PORTScolumn for the app. A value like0.0.0.0:8989->8989/tcpmeans the app answers on port8989on your server. The number on the left is the one that counts. -
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
.envfile, the file keeps the old port. See Port already in use for how to change a port. -
Test the address from the file on your server. Replace
URL_FROM_THE_FILEwith theurl:value, for examplehttp://172.17.0.1:8989.Terminal window curl -sS --max-time 10 -o /dev/null -w "%{http_code}\n" URL_FROM_THE_FILEA number such as
200,301or302means the app answers. If you seeConnection refused, the app is not listening there. If it times out after 10 seconds, nothing answers at that address. -
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 OKOK, orserver returned errorwith an HTTP code such as401, means Traefik reached the app. Forbad address,Connection refusedor a timeout, see what each result means in Use a hostname instead of an IP address. -
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.
-
If the app only answers on HTTPS, the
url:line must start withhttps://. See Put any app behind Traefik with Traefikify. -
If the app is slow to start, wait a minute and load the page again.
The app has no Traefik file
Section titled “The app has no Traefik file”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.
-
Find the app’s port. The number on the left in the
PORTScolumn is the one you need.Terminal window dpsWithout the aliases, run
sudo docker ps -a. -
In Deployrr, go to Proxy > Traefik > Traefikify.
-
Enter a name, a subdomain, your server’s local IP address,
httpand the port from step 1. -
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.
Two files use the same names
Section titled “Two files use the same names”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.
-
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 -
If it prints nothing, no names clash.
-
If it prints a name, find the files that use it. Replace
NAME-rtrwith the name it printed.Terminal window sudo grep -rn "NAME-rtr:" appdata/traefik3/rules/$HOSTNAME/ -
Back up the file you will change, as in step 3 above.
-
Rename the router and its service in that file. Change both the
-rtrand-svcnames, and theservice:line that points to the service.
See Run a second copy of an app for a full example.
Apps that use Docker labels
Section titled “Apps that use Docker labels”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.
-
Check that the app is running. From your Docker folder, run
dps(without the aliases,sudo docker ps -a). The status must start withUp. Traefik only reads labels from a running container. -
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. -
Check that
socket-proxyis running in the same list. Traefik reads labels through Socket Proxy. If it’s stopped, see Socket Proxy. -
Read the labels. Replace
NAMEwith the file name from the table, for exampleauthelia.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 useschain-basic-authby default. Security > Manage Auth can change it. Authelia, Authentik and TinyAuth usechain-no-authfor their own page, and Google OAuth useschain-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.
- The
-
Check that the app is on the
traefik_proxynetwork. Traefik reaches label apps only there.Terminal window sudo docker inspect -f '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' NAMEThe output must include
traefik_proxy. -
If you changed a label, Traefik doesn’t see it until you recreate the app. Saving the file is not enough.
Terminal window dcrec NAMEWithout the aliases, run this. Replace
YOUR_DOCKER_FOLDER,HOSTNAMEandNAMEwith your own values.Terminal window sudo docker compose --profile all -f YOUR_DOCKER_FOLDER/docker-compose-HOSTNAME.yml up -d --force-recreate --remove-orphans NAMESecurity > Manage Auth recreates the app for you when it changes a label.
Which files Traefik loads
Section titled “Which files Traefik loads”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:
dcrec traefikWithout the aliases, run:
sudo docker compose --profile all -f YOUR_DOCKER_FOLDER/docker-compose-HOSTNAME.yml up -d --force-recreate --remove-orphans traefikReplace YOUR_DOCKER_FOLDER and HOSTNAME with your own values. Recreating Traefik drops web connections for a few seconds.
Check it worked
Section titled “Check it worked”-
Open
https://APP.YOUR_DOMAINin a private browser window. ReplaceAPPandYOUR_DOMAINwith your own values. -
You see the app, or the login page of your login method.
-
Follow the Traefik log while you load the page. No new error lines appear for the app.
Terminal window traefiklogsPress
Ctrl+Cto stop.
If the browser shows a certificate warning instead, see Traefik can’t get a Let’s Encrypt certificate.

