Skip to content
Serverküche
Search

Loading search …

Error finder: look up self-hosting error messages

Container won't start, certificate missing, mail stuck? Search your error message – every answer comes from a setup we got running ourselves.

Every card here comes from a tutorial on this site – from an error we actually ran into while setting things up on the test server. Type the error message (address already in use, NXDOMAIN, Unauthorized) or describe the symptom in your own words.

400 findings from real setups

The sign-in bounces straight back and Outline shows “Authentication failed”.

Look at Authentik’s logs: docker compose logs server | grep -i grant. If it says Invalid grant_type for provider, the provider’s Grant types field is empty. In Authentik 2026.x Authorization Code has to be listed there explicitly; otherwise the sign-in aborts with invalid_request before the login mask even appears. Outline only logs OAuth error during authentication: The request is otherwise malformed – the actual cause is always on the Authentik side.
Read on: Outline: The Modern Team Wiki with an Authentik Login →

After signing in you get redirect_uri back as an error.

The address stored in Authentik has to be exactly https://wiki.YOUR_DOMAIN/auth/oidc.callback, with the same name that URL= in Outline’s .env names. A different hostname, an extra slash or http instead of https is enough for a rejection. With matching mode Strict there is no leeway – that is the point.
Read on: Outline: The Modern Team Wiki with an Authentik Login →

Outline shows no sign-in page any more and jumps straight to Authentik.

That is not a fault: with exactly one configured identity provider Outline skips its own selection page. As soon as you set up a second route it comes back. If you want to see the page, call it with a notice parameter, for example after a failed attempt.
Read on: Outline: The Modern Team Wiki with an Authentik Login →

Uploads fail when you bind a host folder instead of using the volume.

Outline runs inside the container as nodejs with UID 1001 and cannot write into a root-owned folder – on hardened servers with umask 027 even less so. Either stay with the named volume, or run chown -R 1001:1001 on the directory. You can check with docker exec outline ls -la /var/lib/outline/data.
Read on: Outline: The Modern Team Wiki with an Authentik Login →

Outline starts, but nobody can sign in, and the log is missing the line OIDC plugin registered.

Then at least one of the six OIDC_ variables is empty. Outline does not report this as an error – it simply starts without a sign-in route. Check with docker exec outline env | grep OIDC whether all values arrive; a common cause is a $ in the client secret, which Compose expands under environment:. With env_file: as used here that does not happen.
Read on: Outline: The Modern Team Wiki with an Authentik Login →

Traefik answers with 502 Bad Gateway even though all four containers are running.

The nginx inside the web container listens on port 8000, not on 80, because it runs unprivileged. Set traefik.http.services.jitsi.loadbalancer.server.port=8000. You can look it up with docker exec jitsi-web ss -lnt; the port actually in use is right there. The same error appears when traefik.docker.network=proxy is missing and Traefik picks up the container address from the internal meet.jitsi network, which it cannot reach itself.
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →

The web container starts but reports cp: cannot stat '/config/.': Permission denied and serves nothing.

The mounted folders under /opt/jitsi/config belong to root while the containers run as UID 1000. A chown -R 1000:1000 /opt/jitsi/config and a restart fix it. On hardened servers with umask 027 this hits you every time, because newly created folders then get 0750.
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →

With two people everything works, from the third participant on nobody hears or sees anything.

That is the classic picture of a closed UDP port. It only surfaces now, because Jitsi runs two-person calls directly between the browsers and only uses the video bridge from three participants onwards. Check ss -lunp | grep 10000 on the server and the inbound ACCEPT rule for UDP 10000 in both firewalls. The bridge’s logs show it too: docker compose logs jvb | grep -i 'ICE state' then shows transitions to Terminated without a connection ever being established.
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →

Everyone is in the room, but nobody hears or sees anybody.

That is almost always the media path, not the conference. Check docker compose logs jvb | grep "static mapping" first. If there is no line with your public address, JVB_ADVERTISE_IPS is missing from the .env and the video bridge announces its container address to the browsers. If the address is right, the next suspect is UDP 10000 in the firewall, in both of them (the one on the server and the one at the provider). In the netcup SCP that means a policy of its own with an inbound ACCEPT rule on UDP 10000; a web template covering 80/443 does not include it.
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →

After docker compose down the moderator account is gone.

Prosody stores accounts under /var/lib/prosody, and that directory is not mounted in the official template: the accounts disappear along with the container. The mount ./config/prosody/data:/var/lib/prosody:Z fixes it; afterwards the accounts live on the host under config/prosody/data/data/meet%2ejitsi/accounts/. An account that is already lost is simply created again.
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →

The “Waiting for a moderator” dialog stays up even after logging in.

Then the account does not exist in the domain Jitsi looks in. Registration happens against meet.jitsi, the internal domain from the .env, not your real one. Check with docker exec jitsi-prosody prosodyctl --config /run/prosody/config/prosody.cfg.lua register NAME meet.jitsi PASSWORD: if the command reports “User already exists”, the domain is right and the password is wrong.
Read on: Jitsi Meet: Your Own Video Conferences Without Zoom →

/_matrix/client/versions returns the Element start page instead of JSON.

Both routers listen on the same host and Traefik checked the wrong one first. Set traefik.http.routers.synapse.priority=100 and …element.priority=10. Without explicit numbers Traefik sorts by rule length, and that result changes as soon as another rule joins. After the change docker compose up -d is enough; Traefik re-reads the labels straight away.
Read on: Matrix Part 2: Element, federation and admin →

The Element container does not start and reports cp: can't open '/app/config.json': Permission denied.

The element-config.json on the host is not readable for the container. This happens reliably on servers with umask 027, because new files then get 0640 and no read bit for others. chmod 0644 /opt/matrix/element-config.json and restart. The same applies to every configuration file you hand into a container as a bind mount.
Read on: Matrix Part 2: Element, federation and admin →

Element hangs at “Confirm your digital identity”, and “Use recovery key” is greyed out.

You are signing in on another device and did not create a recovery key on the first one (step 5). If an old device is still signed in, take “Use another device” and confirm there. Otherwise only “Can’t confirm?” followed by your account password remains: Element then resets the identity; account, contacts and rooms stay, but messages from before remain unreadable. Create the recovery key right afterwards.
Read on: Matrix Part 2: Element, federation and admin →

Signing in suddenly fails with M_LIMIT_EXCEEDED.

The answer contains retry_after_ms, the waiting time in milliseconds. Synapse rate-limits login attempts per account and per IP; that hits you when you build several sessions in a row or test with scripts. For permanent operation it can be loosened through the rc_login block in homeserver.yaml, only you should not, because that exact brake is what stops guessing attacks.
Read on: Matrix Part 2: Element, federation and admin →

The device list and the logs show 172.x.x.x instead of the real visitor IP.

This only affects requests over IPv6, which, on a domain with an AAAA record, is most of them. The proxy network is created with docker network create proxy in the Traefik tutorial, and that is an IPv4-only network. Docker then cannot rewrite an incoming IPv6 connection onto the container directly and sends it through a helper process that replaces the source address with the bridge gateway’s; over IPv4 the address is correct the whole time. The fix is a network with IPv6: docker compose down in every stack, then docker network rm proxy && docker network create --ipv6 --subnet fd00:cafe::/64 proxy and bring everything back up; the steps are in Reverse proxy with Traefik. Afterwards the real address shows up in X-Forwarded-For over IPv4 and IPv6.
Read on: Matrix Part 2: Element, federation and admin →

Synapse refuses to start and reports IncorrectDatabaseSetup: Database has incorrect collation.

The database was created with a language-dependent collation such as de_DE.utf8; Synapse expects C. That cannot be changed afterwards, because the collation is fixed when the database is created. Delete the volume and start again with POSTGRES_INITDB_ARGS: "--encoding=UTF8 --lc-collate=C --lc-ctype=C". The error message offers allow_unsafe_locale as a way out; do not take it, because wrongly sorted indexes will bite you later during searches.
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →

The federation tester reports FederationOK: false even though the site loads in a browser.

Then the delegation is usually wrong. Check curl -s https://YOUR_DOMAIN/.well-known/matrix/server. The answer has to contain the host including the port, something like {"m.server":"YOUR_DOMAIN:443"}. If you get a 404 here, serve_server_wellknown: true is missing from the configuration or another service intercepts the path. Also common: the server name in the delegation points at a host whose certificate is issued for a different name.
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →

The logs show Traefik’s IP for every access instead of the visitor’s.

x_forwarded: true is missing from the listeners block. Synapse only evaluates the forwarding headers when you explicitly allow it. Without the real source address you can neither trace abuse nor use fail2ban sensibly.
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →

Logging in fails with M_FORBIDDEN even though the password is right.

Check that you really are logging in at the right server: the user ID is @name:server_name, not @name:host. If server_name and host differ and the client delegation is missing, your client ends up in the wrong place. curl -s https://YOUR_DOMAIN/.well-known/matrix/client has to return the homeserver’s base URL.
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →

The server runs but memory gets tight.

Synapse uses little while idle (a good 100 MB) but grows noticeably once you join large, heavily federated rooms, because it keeps track of their entire history. When it gets tight, the first remedy is to leave such rooms and then remove old events with the admin API’s cleanup functions. More memory is the other answer; a homeserver that takes part in real rooms is not happy on 1 GB.
Read on: Matrix: Your Own Chat Server with Synapse (Part 1) →

vmstat shows a steady 100 percent id even though the site feels slow.

Then the bottleneck is not on this server. Check the response time at the service directly instead of through the domain – if the container answers fast and the browser still waits, it is the path there: DNS, the TLS handshake or a congested network, not CPU or RAM.
Read on: When is your server too small? →

Nothing at all in the kernel log, even though a container disappeared.

journalctl -k only shows genuine OOM kills. If a service exits on its own, the reason is in its own log: docker compose logs --tail 50 YOUR_SERVICE. An exit 137 without a matching kernel line is usually a docker stop whose grace period ran out, not a memory problem.
Read on: When is your server too small? →

Load average is high but r and b are both 0.

You are reading the first vmstat line. That one is an average since boot and practically meaningless on a server with 80 days of uptime. Use vmstat 1 5 and evaluate from the second line onwards.
Read on: When is your server too small? →

free -h reports almost no free memory, yet the server runs perfectly.

That is the normal state. The kernel fills unused memory with file cache and hands it straight back when somebody needs it. The column that matters is available; free may happily sit near zero.
Read on: When is your server too small? →

Lots of reclaimable space, but docker image prune -a frees almost nothing.

Then the images are still attached to stopped containers. Run docker container prune first, then the images – or do both at once with docker system prune -a, after checking that every stack you want is actually running.
Read on: When is your server too small? →

The container restarts in a loop and reports error loading flags: flag needs an argument: --config.

While copying the command line the two single quotes after --config were lost – which happens easily when the command travels through several shell layers. Check what actually arrives with docker inspect listmonk --format '{{json .Config.Cmd}}': there has to be an empty argument after every --config. When in doubt, write the Compose file with an editor directly on the server instead of generating it through nested quoting.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →

listmonk no longer starts and reports error reading SMTP config: decoding failed.

An invalid value is stored in the settings – a duration without a unit, for instance. The awkward part: the web interface is then unreachable, so you cannot fix it there. The settings live in the settings table; docker compose exec db psql -U listmonk -d listmonk gets you in and lets you UPDATE the smtp key back to a valid block. Then docker compose restart app.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →

The database container does not start and talks about pg_ctlcluster.

That is the PostgreSQL 18 change: the mount must no longer point at /var/lib/postgresql/data but at /var/lib/postgresql. For an existing database, moving it is not enough – there you need pg_dump with the old major version and an import into the new one.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →

The campaign stays on running and nothing is sent.

Then listmonk cannot reach the SMTP server. docker compose logs app | grep -i smtp shows why; often it is the wrong port (587 instead of 465 or the other way round), a wrong TLS setting, or a provider blocking outbound port 25. The local catcher from step 3 helps narrow it down: if sending there works, the problem is not listmonk.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →

The mails arrive but land in spam.

That is not a listmonk problem. Check that SPF, DKIM and DMARC are right for the sender domain and that the sender address matches the domain you send through – how to do that is in email deliverability. Also avoid image-only HTML, and send to a small list first rather than writing to ten thousand addresses at once.
Read on: listmonk: Your Own Newsletter Server – Privacy-Friendly →

The database container refuses to start and says something about pg_ctlcluster and directory names.

That is the PostgreSQL 18 change: from that major version the mount must no longer point at /var/lib/postgresql/data but one level up at /var/lib/postgresql. The container also aborts when the volume is brand new and empty – the check hangs on the mount, not the content. For an existing database, moving the mount is not enough; there you first need a pg_dump with the old major version and an import into the new one.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →

After moving the mount you get mkdir: can't create directory '/var/lib/postgresql/18/': Permission denied.

You are using a bind mount and the directory on the host belongs to root – the Postgres user inside the container cannot create anything in it. At the old path the image still fixed the permissions itself, at the new one it does not. Either hand the directory to the container user, or use a named volume as we do here, where Docker inherits the permissions from the image.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →

Links you send point at localhost or carry a port.

HedgeDoc does not build links from the Host header but from its configuration. Set CMD_DOMAIN to your domain (name only, no https://, no path), CMD_PROTOCOL_USESSL to true and CMD_URL_ADDPORT to false. The container has to be restarted for a change to take effect.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →

A guest edited your note even though CMD_ALLOW_ANONYMOUS_EDITS is false.

That option only works when CMD_ALLOW_ANONYMOUS is false; with true it has no effect. What counts is the individual note’s permission: if it is on Freely, anyone with the link may write. Set CMD_ALLOW_ANONYMOUS to false, restart the container and set the note to Limited or Locked.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →

Notes such as wp-json or xmlrpc.php show up that nobody created.

Those were bots looking for WordPress. With CMD_ALLOW_ANONYMOUS: "true" together with CMD_ALLOW_FREEURL: "true", every request to a free address creates a new note. Set CMD_ALLOW_ANONYMOUS to false and restart the stack. The notes already created have no owner who could delete them in the interface; you remove them in the database: docker compose exec database psql -U hedgedoc -d hedgedoc -c 'DELETE FROM "Notes" WHERE "ownerId" IS NULL;' – their revisions go with them.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →

An outsider only gets a redirect to the start page from the published link.

Then the note is on Limited or Protected – both levels lock guests out completely, published versions included. For “read only, but for everyone”, Locked is the right choice. CMD_ALLOW_ANONYMOUS has nothing to do with it: the option only controls whether guests may create notes, not whether they may read them.
Read on: HedgeDoc: Shared Markdown Notes in Real Time →

Pingvin Share X: The page answers with 403 Forbidden.

The lock from step 1 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →

The links you send point to http://localhost:3000.

The App URL under Configuration → General is still on its default. Pingvin does not learn its public address by itself – the reverse proxy does not tell it. Enter https://YOUR_DOMAIN and save; links you already sent have to be recreated.
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →

Every visitor shows up with the same IP in the access logs.

That is the address from the Docker proxy network, and TRUST_PROXY: "true" is missing from the Compose file. Only with it does Pingvin evaluate the X-Forwarded-For header. But set it only when a proxy really is in front – without one, any client can invent its own source IP.
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →

A large upload aborts halfway through.

Check Max size under Configuration → Share first; the default is 1 GB, and the interface tells you before you even upload (“Maximum total upload size: 1 GB.”). If that is not it, Chunk size is the next lever: pieces smaller than the default 10 MB are more reliable on shaky connections, larger ones faster on stable ones.
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →

Strangers are creating accounts on your instance.

Then Allow registration is still on – the shipping state. Switch it off under Configuration → Security & Access and delete the foreign accounts under Administration → User management. To verify: curl -s -o /dev/null -w "%{http_code}\n" https://YOUR_DOMAIN/auth/signUp has to return 307 afterwards, not 200.
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →

You get logged out immediately after signing in.

Usually Secure cookies is enabled while you are visiting over http:// – the browser then discards the cookie. Open the site over HTTPS. If you deliberately run Pingvin without TLS, the switch has to stay off; the setting says as much itself: “If enabled, the site will not function when accessed over HTTP.”
Read on: Pingvin Share X: Sharing Large Files Without WeTransfer →

eosctl compute vm delete reports nothing and the VM keeps running.

eos only deletes VMs that are powered off and doesn’t say so. Run eosctl compute vm power-off first, wait until power_state is stopped, then delete (step 6).
Read on: Automating netcup eos with eosctl and OpenTofu →

exec doesn’t work right after creation.

started only means the VM is running. The agent exec talks to needs another half minute – wait until agent_ready is true (step 4).
Read on: Automating netcup eos with eosctl and OpenTofu →

Only the first of several commands returns output.

The inner quotes in bash -c are single quotes. Use escaped double quotes as in step 5.
Read on: Automating netcup eos with eosctl and OpenTofu →

OpenTofu aborts with a permission error while creating resources.

Every credential can read, but writing needs a role. This setup needs compute:network-manager and compute:vm-manager. Also check the client credentials list to see whether it has expired, and create a new one if necessary.
Read on: Automating netcup eos with eosctl and OpenTofu →

tofu init can’t find the provider.

The source must include the hostname: dl.eoscloud.io/eos/eoscloud. Without it, OpenTofu searches its own registry, where the provider doesn’t live.
Read on: Automating netcup eos with eosctl and OpenTofu →

The login fails with the correct password even though the hash is right.

Then the hash is probably in a .env file or under environment:. Docker Compose interpolates $ characters in values from env files too, turning $argon2id$v=19$m=65540,... into =19=65540,t=3,p=4/Ntxaqbs... – and it only warns with The "argon2id" variable is not set. Either double every $ to $$, or do it the way we did and put the hash in config.yaml, where Compose never looks.
Read on: code-server: VS Code in the Browser on Your Own Server →

Traefik answers with 401 even though you typed the right BasicAuth password.

Same cause, different place: every $ of the bcrypt hash in the basicauth.users label has to be doubled. Check what actually arrives with docker compose config – a mangled hash there means the doubling is missing.
Read on: code-server: VS Code in the Browser on Your Own Server →

The terminal says bash: python3: command not found.

The official image contains only the editor, no language runtimes – git, curl and sudo are there, nothing more. Build the derived image from step 2 and restart with docker compose up -d --build. Installing into the running container only helps until the next restart.
Read on: code-server: VS Code in the Browser on Your Own Server →

code-server cannot save a file and reports Permission denied.

The folders under projekte belong to root instead of UID 1000. That happens as soon as you create a directory as root on the host. chown -R 1000:1000 /opt/code-server/projekte fixes it; the habit worth building is to create new projects from inside the editor rather than on the host.
Read on: code-server: VS Code in the Browser on Your Own Server →

sudo in the terminal aborts with The "no new privileges" flag is set.

That is not a defect but the effect of security_opt: no-new-privileges:true. Do not remove that line – it is the only reason the bundled coder ALL=(ALL) NOPASSWD:ALL in /etc/sudoers.d/nopasswd is useless to anyone. Whatever you need permanently belongs in the Dockerfile.
Read on: code-server: VS Code in the Browser on Your Own Server →

Outgoing mail runs into a timeout on port 25, 465 or 587.

That isn’t your configuration but netcup’s default policy “netcup Mail block”. Take it off the server in the SCP under Firewall → Policies – no ticket needed, see netcup firewall setup.
Read on: 100 days of netcup: what nobody tells you beforehand →

DNS or time synchronisation doesn’t work, even though everything outbound is allowed.

The netcup firewall is stateless for UDP and doesn’t automatically let reply packets through. Create inbound rules for source port 53 (DNS) and 123 (NTP).
Read on: 100 days of netcup: what nobody tells you beforehand →

A service responds on the server, but not from outside.

Then the SCP firewall is blocking it, not the one on the server. Only 22, 80 and 443 are open inbound; every additional port needs its own policy. Test with curl from another machine, not from localhost.
Read on: 100 days of netcup: what nobody tells you beforehand →

The disk is full, but you can’t find any large files.

Check Docker: docker system df shows you how much is in images and how much of it is disposable. In our case it was 68 GB out of 73 GB used. docker image prune -a cleans up.
Read on: 100 days of netcup: what nobody tells you beforehand →

A container is killed by the kernel (OOM), even though the server has headroom.

Then a memory limit of the container is kicking in, not that of the host. In that case the log shows constraint=CONSTRAINT_MEMCG. This happened to us exactly once – raise the service’s limit before you think about a bigger server.
Read on: 100 days of netcup: what nobody tells you beforehand →

Requests from outside still get 200 instead of 403.

Almost always the middleware is defined but not attached to the router. The two labels have different jobs: traefik.http.middlewares.vpn-only.ipallowlist.sourcerange=… creates it, traefik.http.routers.YOURROUTER.middlewares=vpn-only uses it. Leave out the second line and everything starts without errors while the service sits wide open – with no error message whatsoever. The @docker suffix is optional as long as middleware and router come from the same provider.
Read on: Make services reachable only over VPN →

Even from inside the VPN you get 403.

Then Traefik sees a different source IP than the VPN client’s. Check with curl -s https://YOUR_DOMAIN/ | grep X-Real-Ip against a whoami container: if it shows a Docker-internal address such as 172.19.0.x or a CDN’s IP, there is another proxy in front. In that case you have to tell Traefik via forwardedHeaders.trustedIPs which predecessor it may believe – without that setting it does not evaluate the header at all.
Read on: Make services reachable only over VPN →

Inside the VPN the name still resolves to the public IP.

The client is not using AdGuard. Check cat /etc/resolv.conf first – if it does not say nameserver 10.8.0.1, then DNS = 10.8.0.1 did not take effect. wg-quick needs a tool that can change the resolver configuration: either resolvconf from the openresolv package or resolvectl from the systemd-resolved package. A minimal Debian 13 ships neither, and then the line does nothing. Whether AdGuard itself answers correctly is a separate check: dig +short @10.8.0.1 YOUR_DOMAIN.
Read on: Make services reachable only over VPN →

The certificate suddenly stops renewing.

The ACME fetch needs the public path. If you deleted the A record in the meantime, closed port 80, or accidentally applied the allowlist globally on the web entrypoint, Let’s Encrypt can no longer reach the challenge. docker compose logs traefik | grep -i acme shows the failure – but only shortly before expiry, not immediately.
Read on: Make services reachable only over VPN →

The service answers inside the VPN, but only sometimes.

That is usually address-family ordering: as long as the name still returns an AAAA answer, the client tries IPv6 first – and lands outside the tunnel on the 403. Create the DNS rewrite for IPv4 only; AdGuard then returns no AAAA for that name at all, and dig +short AAAA @10.8.0.1 YOUR_DOMAIN has to stay empty.
Read on: Make services reachable only over VPN →

You put a public IPv6 address into the allowlist and still get 403.

Traefik compares against the address it actually sees – and over IPv6 that is the bridge gateway’s, as long as the proxy network was created without IPv6. Your real address never enters the comparison. Check it with curl -s -6 https://YOUR_DOMAIN/ | grep X-Forwarded-For from the allowed network: if it says 172.x.x.x, recreate the proxy network with --ipv6 (see Reverse proxy with Traefik). For the VPN case in this tutorial it makes no difference, because WireGuard runs over IPv4 here.
Read on: Make services reachable only over VPN →

SSH reports Connection refused although IP and ACL are right.

No SSH server is running on the VM – the cloud images don’t ship one either. Open the web console, install it with apt install openssh-server and add the package to your cloud-init file for future VMs (section “Cloud-init: the SSH server is missing”).
Read on: netcup eos hands-on: the new cloud in preview →

The key is refused, the log says account is locked.

Your cloud-init file contains ssh_pwauth. That produces a one-line sshd_config without UsePAM yes. Check with wc -l /etc/ssh/sshd_config – if it says 1, delete the file in the web console, reinstall the package with apt install --reinstall -o Dpkg::Options::=--force-confmiss openssh-server and restart the service with systemctl restart ssh. Debian’s full configuration is then back on disk.
Read on: netcup eos hands-on: the new cloud in preview →

The VM has a public IP but isn’t reachable.

The ACL rule is missing. Without a rule, all inbound traffic is blocked; create an allow rule for the port with the VM’s internal IP as destination.
Read on: netcup eos hands-on: the new cloud in preview →

Failed to create ACL Rule right after saving.

The destination is entered as @vm-name. Enter the VM’s internal IP instead, shown on its detail page.
Read on: netcup eos hands-on: the new cloud in preview →

A default IP can’t be attached to the VM.

The two public addresses every network brings along are reserved for outbound traffic and port forwards. Create a separate public IP in the same network and attach that one.
Read on: netcup eos hands-on: the new cloud in preview →

Headscale doesn’t start and reports headscale now requires a new noise.private_key_path field.

The noise: block with private_key_path: /var/lib/headscale/noise_private.key is missing from config.yaml (step 1). You don’t have to create the key yourself, Headscale does that on startup.
Read on: Headscale: Your Own Tailscale Network →

Headscale restarts in a loop, the log says loading policy: open /etc/headscale/policy.json: no such file or directory.

policy.path points to a file that doesn’t exist yet. Create the allow-everything file from step 1 or your real rules from step 7 right away.
Read on: Headscale: Your Own Tailscale Network →

apt-get update reports The repository 'https://pkgs.tailscale.com/...' is not signed.

Look at the line above it, which usually says Failed to parse keyring ... Permission denied (os error 13). The cause is a stricter UMASK (such as 027) on the system: curl -o then creates the key with mode 0640, and apt verifies signatures as the unprivileged user _apt, which cannot read the file. chmod 0644 /usr/share/keyrings/tailscale-archive-keyring.gpg /etc/apt/sources.list.d/tailscale.list fixes it immediately.
Read on: Headscale: Your Own Tailscale Network →

Headscale refuses to start and reports server_url cannot use the same domain as base_domain.

dns.base_domain and the domain in server_url overlap. Headscale rejects that because the control server itself would then be resolved through MagicDNS and could make itself unreachable. Pick a separate, non-public zone such as home.internal for base_domain and validate the file before every restart with docker compose exec headscale headscale configtest.
Read on: Headscale: Your Own Tailscale Network →

The logs say listening without TLS but ServerURL does not start with http://.

That is not a malfunction but the normal state behind a reverse proxy: Headscale speaks HTTP, Traefik handles TLS. You recognise a real problem by curl https://YOUR_DOMAIN/health not returning {"status":"pass"} – in that case it is Traefik, not Headscale.
Read on: Headscale: Your Own Tailscale Network →

A client will not connect and hangs during registration.

Check the client version first with tailscale version: Headscale 0.29 rejects anything below 1.80, and the distribution packages of some LTS systems are older than that. If the version is fine, the next suspect is the pre-auth key – the default lifetime is one hour, and preauthkeys list shows you in the Expiration column whether it is still valid.
Read on: Headscale: Your Own Tailscale Network →

A subnet route is approved and installed on the client, yet the destination stays unreachable.

If the target network is a Docker network on the same host, Docker blocks the traffic itself. Its filter chain contains -A DOCKER ! -i br-XXXX -o br-XXXX -j DROP, and packets arriving via tailscale0 hit exactly that rule. For container networks you therefore do not use a subnet route but publish the service through the reverse proxy as usual. For real LANs, check instead whether net.ipv4.ip_forward=1 is set on the subnet router.
Read on: Headscale: Your Own Tailscale Network →

After setting UMASK 027 a service no longer starts and reports “Permission denied” on its own configuration file.

The new umask applies from your next login onwards, and everything you create with > or cat > after that gets mode 0640 instead of 0644. Services running under their own user – systemd-timesyncd uses DynamicUser, for instance – can then no longer read the file. The journal shows Failed to open ...: Permission denied. Set the permissions explicitly for configuration files that are not owned by root: chmod 0644 /etc/systemd/timesyncd.conf.d/99-lynis.conf.
Read on: How Secure Is My Server? A Self-Audit With Lynis →

After applying the sysctl values none of the containers have network access.

Then net.ipv4.conf.all.forwarding ended up at 0. Lynis suggests it, but without IP forwarding Docker cannot pass packets between the container network and the outside world. Remove the line from /etc/sysctl.d/99-lynis.conf and reset the value immediately with sysctl -w net.ipv4.conf.all.forwarding=1 – restarting Docker alone will not help.
Read on: How Secure Is My Server? A Self-Audit With Lynis →

systemd-timesyncd did not synchronized the time recently persists even though timedatectl reports NTPSynchronized=yes.

Lynis does not check the clock but the age of /run/systemd/timesync/synchronized, and warns beyond 2048 seconds. Since systemd raises its poll interval to exactly 2048 seconds when the clock is stable, the test inevitably runs into the warning. Either lower PollIntervalMaxSec as shown in step 4, or add the test to custom.prf – but do not just ignore it, or you will miss the day time synchronisation really breaks.
Read on: How Secure Is My Server? A Self-Audit With Lynis →

Lynis reports Consider hardening SSH configuration ten times and never says what it means.

The screen output drops the details. They are in the third field of grep "^suggestion\[\]=SSH-7408" /var/log/lynis-report.dat – that gives you the parameter and target value for every line.
Read on: How Secure Is My Server? A Self-Audit With Lynis →

After installing auditd a finding was added instead of removed.

ACCT-9630 reports a running audit daemon with an empty ruleset. That is intended: auditd without rules burns resources without logging anything. Put rules under /etc/audit/rules.d/ and load them with augenrules --load – or uninstall auditd again if you are not going to read the log.
Read on: How Secure Is My Server? A Self-Audit With Lynis →

The container won’t start and reports Operation not permitted.

You dropped one capability too many. The message almost always names the system call – chown(...) failed means CHOWN, setgid means SETGID. Hand back exactly that one (cap_add: [CHOWN]) and restart; work your way towards the minimum instead of adding several capabilities on suspicion.
Read on: Hardening Docker containers with least privilege →

The container is Up according to docker compose ps but doesn’t answer.

Up only means PID 1 is alive – not that the application is working. With nginx the workers die without SETUID/SETGID while the master keeps running. Check with docker exec CONTAINER ps -o pid,user,comm whether there is more than one process, and look at the log: docker compose logs | grep -iE "alert|emerg".
Read on: Hardening Docker containers with least privilege →

Read-only file system at startup.

The application needs a writable directory you haven’t provided as tmpfs yet. The error message names the path; add it under tmpfs:. Careful: real data never belongs in a tmpfs – that is RAM and gone on restart. Keep using a volume for that.
Read on: Hardening Docker containers with least privilege →

The page returns 403 Forbidden, the log says is forbidden (13: Permission denied).

nginx runs as UID 101 and isn’t allowed to read the files in the mounted directory – typical for servers with UMASK 027, where root creates new files without read permission for others. Check with ls -l and fix with chmod -R a+rX site.
Read on: Hardening Docker containers with least privilege →

Permission denied in the tmpfs even though read_only looks right.

A tmpfs belongs to root by default. If you set user:, the mount needs the UID: /var/cache/nginx:uid=101,gid=101. Find the right UID with docker run --rm YOUR_IMAGE id USERNAME.
Read on: Hardening Docker containers with least privilege →

The container is killed without warning and docker inspect shows ExitCode 137.

That is the OOM killer: mem_limit is too tight. Measure the real demand in operation with docker stats --no-stream and set the limit a little above it. Leaving the limit out entirely is the worse option – then the container may take the server down with it.
Read on: Hardening Docker containers with least privilege →

No code prompt appears at all, the login works as before.

Then KbdInteractiveAuthentication is still no – the default on Debian 13. Check what really applies with sudo sshd -T | grep kbdinteractive, and note that files in /etc/ssh/sshd_config.d/ are read in alphabetical order and the first setting wins.
Read on: Securing SSH with Two-Factor Authentication (TOTP) →

After the key you are also asked for the password.

Not a bug but the consequence of UsePAM yes: keyboard-interactive runs the whole PAM stack, including @include common-auth. If you only want key

  • code, comment that line out – with the consequence from the warning in step 7.
Read on: Securing SSH with Two-Factor Authentication (TOTP) →

The code is rejected even though the app shows it right now.

Usually the server clock has drifted. TOTP tolerates only a few seconds. Check timedatectl – it must say System clock synchronized: yes; otherwise enable NTP. Second possibility: you used the same code shortly before and DISALLOW_REUSE forbids that. This also applies if the previous attempt only failed at the password – the code was correct and is therefore used up. The same code is then rejected even with the correct password; only the next one goes through. So simply wait for the next one.
Read on: Securing SSH with Two-Factor Authentication (TOTP) →

After three failed attempts nothing works any more.

That is the rate limit from -r 3 -R 30: three attempts per 30 seconds. Every round counts: after a wrong password the SSH client asks again up to three times, and that alone exhausts the limit. Wait a moment instead of typing on.
Read on: Securing SSH with Two-Factor Authentication (TOTP) →

One user gets in without a code.

Either their ~/.google_authenticator is missing and nullok lets them pass, or a Match block with different AuthenticationMethods applies to them. sudo sshd -T -C user=NAME,host=localhost,addr=127.0.0.1 | grep authenticationmethods shows what really applies to them.
Read on: Securing SSH with Two-Factor Authentication (TOTP) →

Phone lost, no scratch codes.

Then only an access path that does not go through SSH helps: the provider’s VNC console. Log in there and delete the user’s file (rm ~/.google_authenticator) – with nullok they get back in without a code, without it you end up with an account that has no second factor and needs to be set up again.
Read on: Securing SSH with Two-Factor Authentication (TOTP) →

Mail to the outside hangs, the logs show timeouts on port 25.

This isn’t the software, it’s the host: netcup’s default policy “netcup Mail block” blocks 25, 465 and 587 outbound. You take the policy off the server yourself in the SCP under Firewall → Policys – no support case, no ticket. Affects Stalwart and Mailcow equally, see netcup firewall setup.
Read on: Stalwart or Mailcow? Two mail servers compared →

The mail arrives but lands in spam everywhere.

Then reverse DNS (PTR), SPF, DKIM or DMARC are missing. This too is independent of the product and described step by step in email deliverability.
Read on: Stalwart or Mailcow? Two mail servers compared →

Mailcow won’t start, the logs report address already in use for port 80 or 443.

A reverse proxy is already running on the server and Mailcow’s own nginx wants the same ports. Either give Mailcow the host to itself, or bind its nginx to a local port as shown under “What it costs to move in next to a reverse proxy” and put it behind the proxy.
Read on: Stalwart or Mailcow? Two mail servers compared →

After the Mailcow setup all the other containers are suddenly gone.

On an IPv6 host generate_config.sh created /etc/docker/daemon.json and restarted Docker. That’s intended behaviour and prevents an open relay, but it hits the whole host. Containers with restart: unless-stopped come back by themselves, the rest you start by hand.
Read on: Stalwart or Mailcow? Two mail servers compared →

The mail client warns about a self-signed certificate CN=rcgen self signed cert.

Stalwart is still serving its placeholder. Check docker compose logs traefik-certs-dumper first: if it says /traefik/acme.json is not a file, the path in the dumper doesn’t point at the directory holding Traefik’s acme.json. If the files are in the volume, only the reload is missing – Actions → Reload → TLS certificates or a Stalwart restart; registered certificates are served only after that.
Read on: Stalwart or Mailcow? Two mail servers compared →

Containers get killed by the kernel after a short while (OOM).

The server is too small for the stack you chose. With Mailcow and its 18 containers this happens considerably earlier than with Stalwart; as a first measure turn ClamAV off in mailcow.conf with SKIP_CLAMD=y, since the virus scanner is the biggest memory eater.
Read on: Stalwart or Mailcow? Two mail servers compared →

The script aborts while looking up the flows with IndexError: list index out of range.

This only happens right after a fresh installation: /-/health/ready/ already reports 200 while the worker is still importing the bundled flows. At that moment there is often only one flow; all 15 are there 20 to 30 seconds later. Wait briefly and run it again.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

The request redirects to http://localhost/application/o/authorize/….

The embedded outpost does not know its public address: the authentik_host field is empty. Set it to https://YOUR_DOMAIN/ (step 3) – before that every user lands on a dead page.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

Traefik answers with 500, or no redirect happens at all.

Then the middleware cannot reach the outpost. The address has to be resolvable from Traefik’s point of view – so the service name from the compose file, which Docker registers as an alias on the shared network (http://server:9000/outpost.goauthentik.io/auth/traefik), not localhost. From the Traefik folder, check with docker compose exec traefik wget -S -qO- http://server:9000/-/health/live/; the endpoint returns an empty body, hence the -S – what you need to see is HTTP/1.1 200 OK.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

The service is protected but does not know the user.

authResponseHeaders is missing from the middleware. Without that list Traefik discards the identity headers from Authentik’s response – the login works, but the application sees nothing.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

After signing in you end up in a redirect loop.

Usually external_host does not match the address actually being called (http instead of https, with or without a subdomain). It has to be exactly the URL users open the service at.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

The OIDC login fails with „redirect_uri mismatch".

Authentik checks the callback address strictly. Enter exactly the URI the application sends – for Grafana e.g. https://GRAFANA_DOMAIN/login/generic_oauth. A missing trailing slash is enough to break it.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

All signed-in users get in everywhere.

Without a binding to a group an application is open to every authenticated user. Attach a group binding to the application (step 8) and verify with an account that is not in the group.
Read on: Authentik Part 2: Connecting Apps – Forward Auth & OIDC →

Authentik: The page responds with 403 Forbidden.

The lock from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Authentik: single sign-on for all services (Part 1) →

The interface returns Internal Server Error while the container counts as healthy.

Then Authentik cannot read its template directories. Typical for servers with UMASK 027: mkdir creates drwxr-x--- there – and the container runs as user 1000, which cannot enter them. The log says PermissionError: [Errno 13] Permission denied: '/templates/if/error.html'. Fix it with chmod 755 media certs custom-templates in the stack directory and restart.
Read on: Authentik: single sign-on for all services (Part 1) →

The page answers with 404 for minutes even though the containers are running.

On the first start over 550 database migrations run; while they do, /-/health/ready/ returns 404 as well. On the VPS 1000 that was over after 105 seconds, the setup flow another ten to 25 seconds later. docker logs -f authentik-server-1 shows the progress.
Read on: Authentik: single sign-on for all services (Part 1) →

Calling the setup flow gives „Request has been denied."

The setup flow cannot be opened directly via /if/flow/initial-setup/. Go to the root address https://YOUR_DOMAIN/, from where Authentik redirects correctly.
Read on: Authentik: single sign-on for all services (Part 1) →

The „workers" tile shows 0.

The worker container is not running or cannot reach the database. Without it, emails, scheduled tasks and outpost management are left undone – with no error message in the interface. Check docker compose ps and the worker’s logs.
Read on: Authentik: single sign-on for all services (Part 1) →

Traefik answers with 404.

Usually traefik.http.services.authentik.loadbalancer.server.port=9000 is missing. The container listens on 9000; port 9443 is Authentik’s own HTTPS, which we deliberately do not use.
Read on: Authentik: single sign-on for all services (Part 1) →

After a rebuild all sessions are invalid or the login fails.

Then the AUTHENTIK_SECRET_KEY changed – for example because the .env was regenerated. The key has to stay the same for the lifetime of the installation; restore it from your backup.
Read on: Authentik: single sign-on for all services (Part 1) →

The username doesn’t match.

The account created during setup is called akadmin, not your email address. If you want to log in with the address, allow that in the identification stage of the login flow.
Read on: Authentik: single sign-on for all services (Part 1) →

The logs say „middleware … does not exist" and the service answers with 404.

Almost always the provider suffix is missing: a middleware defined in the file provider is called name@file from the perspective of Docker labels. Without the suffix Traefik looks for it among the Docker labels – and finds nothing. The same applies the other way round for name@docker.
Read on: Hardening Traefik: security headers, rate limit & more →

BasicAuth rejects the correct password.

The $ characters in the bcrypt hash were interpreted as variables by Docker Compose. In Compose they have to be doubled ($$2y$$05$$…). docker compose config shows the value that really arrives.
Read on: Hardening Traefik: security headers, rate limit & more →

The rate limit doesn’t seem to work.

Sequential curl calls are too slow: every process opens a new connection, so you stay below the limit. Test in parallel, e.g. with seq 40 | xargs -P 8 -I{} curl … – then the 429s appear.
Read on: Hardening Traefik: security headers, rate limit & more →

After setting the IP allowlist you get 403 yourself.

Most common reason: you entered only your IPv4 but connect over IPv6. Compare curl -4 and curl -6 against your domain and enter both address families (see step 5). Second reason: Traefik does not see your IP but that of the proxy in front of it (Cloudflare, load balancer). Check with traefik/whoami what X-Forwarded-For contains, and use ipallowlist.ipstrategy.depth for multi-stage setups.
Read on: Hardening Traefik: security headers, rate limit & more →

The browser still refuses plain HTTP even though you fixed the configuration.

That is HSTS, not a bug: the browser remembers max-age and enforces HTTPS even when your server no longer offers it. A private window or a different browser helps for testing – and that is why the warning about preload exists above.
Read on: Hardening Traefik: security headers, rate limit & more →

Dockge: The page answers with 403 Forbidden.

The restriction from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Dockge: Manage Compose Stacks in the Browser →

Traefik answers with 404 although the container is healthy.

Usually traefik.http.services.dockge.loadbalancer.server.port=5001 is missing. Inside the container Dockge listens on 5001; without that line Traefik guesses. Also check that the container is attached to the proxy network.
Read on: Dockge: Manage Compose Stacks in the Browser →

The deployment aborts with „no such file or directory".

The host and container paths of the stacks directory do not match. It must be mounted as /opt/stacks:/opt/stacks with DOCKGE_STACKS_DIR=/opt/stacks – Dockge has the host’s Docker daemon do the work, and that daemon only knows host paths.
Read on: Dockge: Manage Compose Stacks in the Browser →

A stack is visible but all buttons are missing.

Then it lives outside /opt/stacks and Dockge shows „This stack is not managed by Dockge." Move the folder as in step 7 – Dockge neither adopts it by itself nor makes a copy.
Read on: Dockge: Manage Compose Stacks in the Browser →

The stack name is rejected.

Only lowercase letters, digits, hyphens and underscores are allowed, because they become the folder and Compose project name. My App fails with Stack name can only contain [a-z][0-9] _ - only, my-app works.
Read on: Dockge: Manage Compose Stacks in the Browser →

After a restart the login is gone.

Then ./data was not mounted persistently – that is where the database and JWT secret live. Check that /opt/dockge/data exists and is bound in the Compose file.
Read on: Dockge: Manage Compose Stacks in the Browser →

The interface is in the wrong language.

Dockge follows the browser and falls back to English for unknown combinations; the settings let you pin the language.
Read on: Dockge: Manage Compose Stacks in the Browser →

Audiobookshelf: The page responds with 403 Forbidden.

The lock from step 3 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

The library stays empty after you create it.

The first scan does not run automatically – that is not a bug but how Audiobookshelf behaves. In the library view, click Scan Library. If it stays empty afterwards, check with docker compose exec audiobookshelf ls -R /audiobooks whether the container sees the files at all, and with ls -ln /opt/audiobookshelf/audiobooks that everything is owned by UID 1000.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

Four MP3 files become four audiobooks instead of four chapters.

The files sit directly in the author folder instead of a shared title folder. Audiobookshelf groups by Author/Title/ – move the files into a subfolder named after the book and scan again.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

Traefik answers with 404 even though the container is running.

Usually traefik.http.services.abs.loadbalancer.server.port=80 is missing. Inside the container Audiobookshelf listens on 80; without that line Traefik guesses and misses. Also check that the container really is attached to the proxy network.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

The address jumps to /audiobookshelf/.

That is normal: the frontend ships with this fixed router path, and ROUTER_BASE_PATH changes nothing at runtime because the path is baked into the image. https://YOUR_DOMAIN remains a valid entry point.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

After switching devices the language is back to English.

The language choice lives locally in the browser, not on the account. Set it once per device via your username → Language.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

The podcast is not found.

The search queries the iTunes catalogue; a typo or a missing entry there leads to „no search results". Use the podcast’s RSS URL instead – the same field accepts both.
Read on: Audiobookshelf: Self-Host Audiobooks & Podcasts →

WordPress: The page answers with 403 Forbidden.

The restriction from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Running WordPress Cleanly with Docker & Traefik →

Redirect loop (ERR_TOO_MANY_REDIRECTS) or mixed-content warnings.

The HTTPS detection is missing. Check that the WORDPRESS_CONFIG_EXTRA block with HTTP_X_FORWARDED_PROTO and the $$ signs is set exactly (see the warning in step 2), and restart the WordPress container.
Read on: Running WordPress Cleanly with Docker & Traefik →

WordPress won’t start, reports “Error establishing a database connection”.

Usually a race condition or a password mismatch. Check that depends_on: condition: service_healthy is set and WORDPRESS_DB_PASSWORD matches MARIADB_PASSWORD exactly. Logs: docker compose logs db.
Read on: Running WordPress Cleanly with Docker & Traefik →

The first start fails even though everything runs later.

The database needs a few seconds to initialize on the very first start. The health check covers this; without it, another docker compose up -d helps.
Read on: Running WordPress Cleanly with Docker & Traefik →

Media uploads fail for large files.

PHP limits the upload size. Create your own uploads.ini and mount it to /usr/local/etc/php/conf.d/ with e.g. upload_max_filesize = 64M and post_max_size = 64M.
Read on: Running WordPress Cleanly with Docker & Traefik →

After a domain change the site points nowhere.

WP_HOME/WP_SITEURL are hard-wired in the Compose file – for a new domain, change them there and restart the container (the values override the database setting).
Read on: Running WordPress Cleanly with Docker & Traefik →

The page doesn’t load, Traefik answers with a 404, even though the container is running.

The health check isn’t healthy yet (see step 2). Check with docker compose ps or docker inspect -f '{{.State.Health.Status}}' linkding-linkding-1; if it stays unhealthy, docker compose logs linkding tells you why.
Read on: linkding: Self-Host Your Bookmarks →

The login form answers with Forbidden (403) CSRF verification failed.

The login page itself loads normally, but Django didn’t consider the request’s origin trustworthy – typical when a proxy in front of Traefik rewrites the Host header or linkding runs under a sub-path. Add LD_CSRF_TRUSTED_ORIGINS: https://YOUR_DOMAIN (with https://, without a path and without a trailing slash) and run docker compose up -d.
Read on: linkding: Self-Host Your Bookmarks →

Title and description aren’t fetched automatically.

The target page blocks automated access or responds too slowly. Enter both by hand or switch the bookmarklet to detection in the browser (step 5).
Read on: linkding: Self-Host Your Bookmarks →

The admin account wasn’t created.

LD_SUPERUSER_NAME and LD_SUPERUSER_PASSWORD only take effect on the first start with an empty database. If data/db.sqlite3 already exists, a later change does nothing. Create the account afterwards: docker compose exec linkding python manage.py createsuperuser.
Read on: linkding: Self-Host Your Bookmarks →

The API or the extension answers with 401.

Either the token is missing or it’s wrong: {"detail":"Authentication credentials were not provided."} means the Authorization header never arrived, {"detail":"Invalid token."} means the token doesn’t match. Since a token is only shown once, creating a new one under Settings → Integrations is faster than hunting for the old one. Enter exactly https://YOUR_DOMAIN as the server, with no path after it.
Read on: linkding: Self-Host Your Bookmarks →

Navidrome: The page responds with 403 Forbidden.

The lock from step 3 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Navidrome: Stream Your Own Music Like Spotify →

The library stays empty.

Either there are no files in the mounted music folder, or the permissions are wrong. Check: docker compose logs --no-log-prefix | grep "Scanner:" shows tracksImported. If it’s 0 everywhere, check the path and that the music folder is owned by UID 1000 (see Users & permissions).
Read on: Navidrome: Stream Your Own Music Like Spotify →

Tracks appear unsorted or without cover art.

The files’ metadata is incomplete – Navidrome sorts by tags, not by filenames. What it actually reads from a file is shown by docker compose exec navidrome /app/navidrome inspect "/music/Artist/Album/Track.mp3": under rawTags you get the tags exactly as they sit in the file. If album or albumartist are missing there, re-tag the files (e.g. with Picard) and let Navidrome rescan.
Read on: Navidrome: Stream Your Own Music Like Spotify →

New music doesn’t show up.

The scan only runs hourly (ND_SCANNER_SCHEDULE). Trigger an immediate scan via the refresh icon in the top right of the web interface, or wait for the next interval. If the files were just uploaded, what’s usually missing is the chown -R 1000:1000 from step 2.
Read on: Navidrome: Stream Your Own Music Like Spotify →

The app won’t connect.

Almost always the server URL: it must be https://YOUR_DOMAIN (with https://, no path). If the ping.view call from step 8 answers cleanly, it’s the credentials – since version 0.64.1 Navidrome additionally throttles repeated failed logins through the Subsonic API, so after a few typos a short break helps.
Read on: Navidrome: Stream Your Own Music Like Spotify →

Playback stutters on large FLAC files over mobile.

The bandwidth isn’t enough for the original. Set a transcoding profile and a ceiling for your app’s player (step 9) – the entry only appears under Players after the app has connected once.
Read on: Navidrome: Stream Your Own Music Like Spotify →

Container won’t start: “unable to open database file”.

DB_NAME: /data/hc.sqlite is missing or the data folder isn’t owned by UID 1000. Set the path and chown -R 1000:1000 /opt/healthchecks/data (see the warning in step 2).
Read on: Healthchecks: monitor cron jobs and backups →

The container shows Restarting and the domain returns 404.

docker compose logs shows (hc.api.E002) The hostname in settings.SITE_ROOT is not found in settings.ALLOWED_HOSTS. Put exactly the hostname from SITE_ROOT into ALLOWED_HOSTS – without https:// – and restart with docker compose up -d.
Read on: Healthchecks: monitor cron jobs and backups →

Login fails with 403 (CSRF error on submit).

Healthchecks then treats the request as plain HTTP, and Django rejects the form because the https://… origin doesn’t match. The image detects HTTPS via the X-Forwarded-Proto header that Traefik sends – if it’s missing, for instance behind a differently configured proxy, you get this error. A CSRF_TRUSTED_ORIGINS variable doesn’t help: Healthchecks doesn’t read it.
Read on: Healthchecks: monitor cron jobs and backups →

The check won’t turn “green” even though the job runs.

Check whether the curl ping actually runs and hits the right UUID: curl -v https://YOUR_DOMAIN/ping/UUID should return OK. On the detail page the log shows whether and from which IP pings arrive.
Read on: Healthchecks: monitor cron jobs and backups →

I get no notification on “down”.

No integration channel is assigned, or (for email) the SMTP settings are missing. Set up a channel under “Integrations” and assign it to the check.
Read on: Healthchecks: monitor cron jobs and backups →

Stirling-PDF: The page answers with 403 Forbidden.

The lock from step 1 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

The page doesn’t load (Traefik 404) even though the container is running.

The health check isn’t healthy yet – Traefik deliberately doesn’t route then. Wait 20–30 seconds after start; check the status with docker inspect -f '{{.State.Health.Status}}' stirling-stirling-pdf-1. Only once it says healthy does the domain answer.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

Login with admin/stirling fails.

Either the password was already changed (then use the new one), or the config in the configs volume is inconsistent. To reset, stop the app and check the user config in the configs folder; if in doubt clear the folder (note: this resets all settings, after which the default credentials apply again).
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

I’m suddenly logged out after the password change.

That’s not a fault: Stirling-PDF discards the session as soon as the password has been set. Just log in again with user admin and the new password.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

A newly added OCR language doesn’t show up.

The application reads /usr/share/tessdata at start. So run docker compose restart after copying the .traineddata – and check that the file really sits in the mounted data folder and ends in .traineddata.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

Office conversions or OCR are missing entirely.

Then you’re running the -ultra-lite variant of the image: it lacks LibreOffice and Tesseract, so those tools have no function. Switch to the standard tag (stirlingtools/stirling-pdf:3.2.2) and run docker compose up -d – the price is about 2.5 GB more image.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

Large files cause errors or long waits.

OCR and conversion are memory-intensive. On a small VPS RAM can run short – then either process smaller files or move to a larger product.
Read on: Stirling-PDF: The PDF Toolbox on Your Own Server →

Syncthing: The page answers with 403 Forbidden.

The lock from step 2 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Syncthing: sync files between devices without a cloud →

The container won’t start / restart loop with permission denied.

The permissions on the config or data folder are wrong. chown -R 1000:1000 /opt/syncthing/config /opt/syncthing/data and restart (see the warning in step 1).
Read on: Syncthing: sync files between devices without a cloud →

The browser reports an invalid certificate even though the container is running.

The health check isn’t healthy yet, so Traefik doesn’t know the domain and answers with its fallback certificate (with curl -k you’d get a 404). Wait up to 60 seconds after start, check docker inspect -f '{{.State.Health.Status}}' syncthing-syncthing-1 and reload the page. If it stays that way, look in docker compose logs for why the health check fails.
Read on: Syncthing: sync files between devices without a cloud →

Two devices won’t connect.

Check three things: is port 22000 (TCP+UDP) open in both firewalls – UFW on the server and, where applicable, the netcup firewall in the SCP? Did you enter the ID on both devices (pairing is mutual)? And is the ID exact (typos are caught easily thanks to a built-in checksum)? A “Disconnected” state with correctly entered IDs almost always points to the firewall port.
Read on: Syncthing: sync files between devices without a cloud →

A folder is stuck at “Syncing 0%”.

Usually the share confirmation is missing on the other side, or the folder ID doesn’t match – it must be identical on both devices. Also check the write permissions in the target folder.
Read on: Syncthing: sync files between devices without a cloud →

No access after setting the GUI password.

Forgot the password? You can reset it in config.xml (<gui> block) by removing the <user> and <password> lines and restarting Syncthing – then the interface is reachable without a login again (and you set it anew immediately).
Read on: Syncthing: sync files between devices without a cloud →

FreshRSS: The page responds with 403 Forbidden.

The lock from step 1 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: FreshRSS: Your Own RSS Reader →

After setup you end up back at step 1 of the wizard.

The installation only counts as finished once you click “Complete installation” in the last step – close the browser window before that and the next visit drops you back into the wizard. Just walk through it again and click all the way to the end this time. You don’t have to worry about file permissions along the way: the official image fixes group and mode of the data directory on every start – including a folder restored from a backup.
Read on: FreshRSS: Your Own RSS Reader →

Feeds don’t refresh automatically.

First check whether the cron entry inside the container exists at all: docker compose exec freshrss crontab -l must print a line starting with your CRON_MIN minutes (13,43 * * * * …). If it’s missing, CRON_MIN wasn’t set at start – add the variable and run docker compose up -d. What the last run did is logged inside the container at /tmp/FreshRSS.log (docker compose exec freshrss tail /tmp/FreshRSS.log). You can trigger a refresh anytime with docker compose exec -u www-data freshrss ./cli/actualize-user.php --user admin.
Read on: FreshRSS: Your Own RSS Reader →

The mobile app won’t connect and reports a server error.

If https://YOUR_DOMAIN/api/greader.php answers 503 Service Unavailable!, the server-wide switch from step 6 is missing: without the “Allow API access” box under Administration → Authentication, even a configured API password gets you nowhere. With both in place the API answers a login with 200 and returns an Auth token.
Read on: FreshRSS: Your Own RSS Reader →

A feed from your own network stays empty.

Since 1.30 FreshRSS blocks local targets; the log says URL is not allowed to be resolved or Fetching this URL is not allowed, because the host’s IP is not in the allowlist. The fix is the INTERNAL_HOST_ALLOWLIST environment variable (see the box above) – or the same list under Administration → System configuration. If a feed from the public internet stays empty, the URL is usually an HTML page instead of the feed; search the page source for application/rss+xml.
Read on: FreshRSS: Your Own RSS Reader →

Older articles disappear after a while.

That’s archiving, and its defaults are deliberately strict: FreshRSS keeps articles for three months and at most 200 per feed, but never fewer than 50 – favourites and labelled articles are left alone. If you want to scroll back further, raise the values under Settings → Archiving or per feed in its settings; the database grows accordingly.
Read on: FreshRSS: Your Own RSS Reader →

systemctl start fails, status shows status=203/EXEC.

systemd couldn’t execute the program from ExecStart; the journal says Unable to locate executable. Either the path is wrong, or the file is missing its executable bit (chmod +x). Without a leading /, systemd only searches /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin (check with systemd-path search-binaries-default) – so your own script under /opt or /root needs an absolute path.
Read on: Understanding systemd: units, journal & timers →

systemd warns “The unit file, source configuration file or drop-ins of … changed on disk”.

You edited a unit file, but systemd doesn’t pick up changes automatically. After every change under /etc/systemd/system/: systemctl daemon-reload.
Read on: Understanding systemd: units, journal & timers →

The timer doesn’t show up in list-timers.

It wasn’t enabled. systemctl enable --now SERVICE.timer – and remember the timer triggers the service, so you need both files (.service and .timer).
Read on: Understanding systemd: units, journal & timers →

systemctl enable answers “The unit files have no installation config”.

The unit is missing the [Install] section with WantedBy=; in systemctl status you spot it by the static in the Loaded: line. Without [Install] systemd doesn’t know when to start the unit automatically – for timers it needs WantedBy=timers.target.
Read on: Understanding systemd: units, journal & timers →

The journal is huge / eats disk.

By default it grows in bounds, but you can trim it: journalctl --vacuum-time=14d deletes entries older than 14 days, journalctl --disk-usage shows the consumption.
Read on: Understanding systemd: units, journal & timers →

“Host validation failed” instead of the dashboard.

The most common trap: HOMEPAGE_ALLOWED_HOSTS is missing or has the wrong domain. Enter exactly the domain you access it under, then docker compose up -d.
Read on: Homepage: a dashboard for your self-hosted services →

The resource widgets show no or wrong values.

Homepage reads CPU and RAM from within the container (no socket needed). If disk: / shows the container filesystem instead of the host disk, mount the desired path as an additional volume (e.g. - /:/host:ro and disk: /host).
Read on: Homepage: a dashboard for your self-hosted services →

An icon doesn’t load.

The name doesn’t match the icon catalog. Write the service name lowercase and without spaces (nextcloud.png), or place a custom image in the icons folder (mounted to /app/public/icons) and reference it as /icons/name.png. Homepage only finds new custom images after docker compose restart; until then the path returns a 404.
Read on: Homepage: a dashboard for your self-hosted services →

The container tile shows no status.

The value at container: must be the exact container name. Find it with docker ps --format '{{.Names}}' – with Compose it’s usually folder-service-1 (e.g. traefik-traefik-1).
Read on: Homepage: a dashboard for your self-hosted services →

Changes to the YAML files don’t take effect.

If it’s the title or layout from settings.yaml, all that’s usually missing is a click on the refresh icon at the bottom right (see step 8). Otherwise a syntax error often aborts the parsing. YAML is indentation-sensitive – check the logs with docker compose logs homepage for error lines and use consistent spaces (no tabs).
Read on: Homepage: a dashboard for your self-hosted services →

You get “Authentication error – Auth is disabled or misconfigured” instead of the sign-in form.

Then HOMEPAGE_AUTH_ENABLED is set but the secret or the password arrives empty in the container – usually because the .env sits in the wrong folder or is missing a line. The log says Password auth is enabled but required settings are missing; docker compose config shows you which values Compose actually substitutes.
Read on: Homepage: a dashboard for your self-hosted services →

The container stays unhealthy.

Almost always the IPv6 trap from step 4: the health check queries localhost but nginx only listens on IPv4. Switch to http://127.0.0.1/. Check with docker inspect --format '{{.State.Health.Status}}' CONTAINER.
Read on: Host your own website with Hugo →

Traefik shows 404 page not found (instead of your site).

That’s the Traefik 404, not the nginx one – Traefik finds no matching router. Most common causes: the container isn’t healthy yet, the Host() rule has the wrong domain, or the proxy network isn’t external. See the 502/404 chapter in Understanding Docker networks.
Read on: Host your own website with Hugo →

All links and images are broken.

The baseURL in hugo.toml doesn’t match the real domain. Hugo bakes absolute URLs based on this value – fix it and rebuild.
Read on: Host your own website with Hugo →

A post doesn’t appear.

Check the date in the front matter: if it’s in the future, Hugo won’t build the post (see the warning box in step 3). A draft: true also hides content in a normal build.
Read on: Host your own website with Hugo →

module "PaperMod" not found in "/src/themes/PaperMod" during the build.

The theme folder is missing from the build context – usually because it’s a Git submodule that wasn’t copied, or a .dockerignore excludes it. Store the theme as a real folder as in step 1.
Read on: Host your own website with Hugo →

Container can’t reach another by name (bad address).

Both aren’t on the same named network, or one uses the default bridge (no DNS). Check which networks a container is on with docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' CONTAINER.
Read on: Docker networks: bridge, internal DNS & proxy network →

Docker networks: Traefik returns 502 Bad Gateway.

Almost always Traefik and the app are on different proxy networks because the network was created twice. Make sure external: true is set in Compose and check with docker network inspect proxy whether both containers are listed.
Read on: Docker networks: bridge, internal DNS & proxy network →

network proxy declared as external, but could not be found on up.

The external network doesn’t exist yet. Create it once: docker network create --ipv6 --subnet fd00:cafe::/64 proxy. Do not let Traefik create the network itself – it then comes up without IPv6, and behind the proxy IPv6 visitors show up as the gateway address instead of their real IP.
Read on: Docker networks: bridge, internal DNS & proxy network →

Database has internet despite internal.

It’s also attached to a non-internal network (e.g. proxy). A container has the sum of the access of all its networks – the DB belongs only on the internal network, never on the proxy network.
Read on: Docker networks: bridge, internal DNS & proxy network →

Two stacks collide on the subnet.

Docker assigns 172.x ranges automatically, but with many networks the pool can run short (could not find an available, non-overlapping IPv4 address pool). Clean up unused networks: docker network prune.
Read on: Docker networks: bridge, internal DNS & proxy network →

Permission denied even though the permissions look right.

Check the permissions of the parent directory: if it’s missing the x bit, you can’t reach the file at all, no matter what its own permissions are. ls -ld /path/to/folder shows it.
Read on: Understanding Linux Users, Groups & File Permissions →

docker ps still says “permission denied” after usermod -aG docker.

The new group isn’t active in the current session yet – log out and back in (see the warning box in step 7). id in the new session must show docker.
Read on: Understanding Linux Users, Groups & File Permissions →

New files have unexpected permissions.

That’s set by the umask – it subtracts permissions from the defaults. On Debian 13 root has 0022 (files 644, directories 755), normal users with their own group have 0002 (664 and 775). Check it with the umask command (no argument).
Read on: Understanding Linux Users, Groups & File Permissions →

A container won’t write to the volume.

The process inside the container runs under a specific UID (often not root). Set the owner of the host directory to match: chown -R 1000:1000 ./data – the image’s docs name the correct UID (environment variables like PUID/PGID).
Read on: Understanding Linux Users, Groups & File Permissions →

usermod dropped the user from groups.

You used -G without -a. -G replaces the secondary groups. Always use usermod -aG. Repair: re-add the missing groups with usermod -aG group1,group2 user.
Read on: Understanding Linux Users, Groups & File Permissions →

The search returns nonsense after the model switch.

The photos are still (or partially) indexed with the old model – old and new vectors don’t mix. Start the All run under Job Queues → Smart Search and wait until the queue is empty. Exactly this mixed state also occurs if you save the setting but forget the re-index.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →

With an nllb-… model the search is no better than before.

Immich doesn’t offer the language hint these models expect (see the warning box in step 3). Switch to an XLM-… or SigLIP2 model and re-index.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →

The ML container exits with exit 137 after the model switch.

Out of memory: the new model no longer fits next to the server, the database and your other services. Either pick a smaller model or add RAM – the XLM base model uses around 1 GB for the ML container alone.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →

The external library stays empty after the scan.

Almost always the path is wrong: the import path must be the container path (/mnt/archive), not the host path. Check with docker compose exec immich-server ls /mnt/archive whether the container sees the files at all – if nothing shows up, the volume entry is missing or you skipped docker compose up -d after the change.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →

The phone only backs up while the app is open.

On Android, battery optimization kills the background worker (exempt the app, see step 1); on iOS, Background App Refresh is off or iOS deprioritizes the app – opening it more often genuinely helps. And: by default, backup runs on Wi-Fi only – photos taken on the go are only “missing” until you’re back home.
Read on: Optimizing Immich: mobile backup & AI search (Part 2) →

Browser shows NET::ERR_CERT_AUTHORITY_INVALID, curl says self-signed certificate.

The server is serving Traefik’s built-in fallback certificate (TRAEFIK DEFAULT CERT) because issuance failed. Almost always: the A/AAAA record points to the wrong IP (check with dig YOUR_DOMAIN) or port 80 is closed in the firewall – the HTTP-01 challenge never arrives. The exact cause is in the Traefik logs: docker compose logs traefik | grep -i acme.
Read on: How HTTPS works and what Traefik does for you →

The issuer carries a (STAGING) prefix, for example (STAGING) Ersatz Emmer YR2.

Let’s Encrypt’s test CA is still active – browsers distrust it on purpose. Remove the staging line from the Traefik configuration, empty acme.json, restart the container (details in the Traefik tutorial).
Read on: How HTTPS works and what Traefik does for you →

certificate has expired.

Automatic renewal has been failing for at least 30 days – same list of causes as the first error, just long unnoticed. If the message appears on one device only: check that device’s system clock, TLS is time-sensitive.
Read on: How HTTPS works and what Traefik does for you →

Let’s Encrypt reports too many certificates already issued.

Rate limit hit, usually from trial-and-error loops against the production CA. Switch to the staging CA until your setup works – and back up acme.json instead of re-issuing certificates.
Read on: How HTTPS works and what Traefik does for you →

unable to get local issuer certificate on an old client.

The system is missing the root certificate from step 3 – its root store is outdated. On Debian: apt update && apt install ca-certificates.
Read on: How HTTPS works and what Traefik does for you →

AdGuard Home: The page responds with 403 Forbidden.

The lock from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: AdGuard Home: network-wide ad and tracking blocker →

The container won’t start, the log says “listen udp :53: bind: address already in use”.

systemd-resolved (or another DNS service) occupies port 53. disable the stub listener as in step 1, then docker compose up -d again.
Read on: AdGuard Home: network-wide ad and tracking blocker →

docker compose up fails with “cannot assign requested address” for 10.8.0.1.

the WireGuard interface wg0 with 10.8.0.1 doesn’t exist (yet) – Docker can’t bind the port to a non-existent address. first set up the WireGuard VPN and bring wg0 up (ip -br addr show wg0 must show 10.8.0.1), then start the container.
Read on: AdGuard Home: network-wide ad and tracking blocker →

After the setup, the web interface is no longer reachable.

in the wizard, the admin port was set to 80 (the suggestion) instead of 3000 – but Traefik forwards to 3000. in ./conf/AdGuardHome.yaml under http: correct the address to 0.0.0.0:3000 and docker compose restart.
Read on: AdGuard Home: network-wide ad and tracking blocker →

DNS doesn’t filter, even though the device is connected.

the browser uses DNS-over-HTTPS (DoH) and thus bypasses your server completely – Firefox and Chrome have this active by default in part. disable “Secure DNS” / “DNS over HTTPS” in the browser settings. You can check with dig @10.8.0.1 … (always takes effect).
Read on: AdGuard Home: network-wide ad and tracking blocker →

A website is suddenly broken (empty pages, missing images, no login).

overblocking – a block list blocks a domain the site really needs. find the blocked domain in the query log, allow it via right-click/menu (exception) or disable the overly aggressive list.
Read on: AdGuard Home: network-wide ad and tracking blocker →

The runner restarts and reports “cannot ping the docker daemon … certificate is valid for docker, …, not fjr-docker”.

The DinD service is named something other than docker, but its TLS certificate is issued for docker. name the DinD service exactly docker (as above) and address it via DOCKER_HOST: tcp://docker:2376 – then the name matches the certificate.
Read on: Forgejo Actions: your own CI/CD runner with Docker →

The job starts but fails at actions/checkout with a connection error.

The runner was registered with an internal instance URL (http://forgejo:3000). The job containers in DinD can’t resolve this name. re-register with the public URL https://YOUR_DOMAIN (delete the .runner file in the volume first, or recreate the volume).
Read on: Forgejo Actions: your own CI/CD runner with Docker →

The runner doesn’t appear in the overview at all / the registration fails.

Wrong or already-used token, or the runner can’t reach Forgejo. get a fresh token (step 1) and check that the runner container reaches https://YOUR_DOMAIN (docker compose run --rm runner wget -qO- https://YOUR_DOMAIN/api/healthz).
Read on: Forgejo Actions: your own CI/CD runner with Docker →

A job stays “pending” forever.

No runner has a matching label. The workflow uses runs-on: docker, so the runner must carry the label docker. check the labels when registering; the runner overview shows the labels per runner.
Read on: Forgejo Actions: your own CI/CD runner with Docker →

actions/checkout can’t find the action.

Forgejo loads actions from a configured registry (by default data.forgejo.org). If the server is completely cut off from the internet, that fails. allow outbound HTTPS access or mirror actions in an internal registry.
Read on: Forgejo Actions: your own CI/CD runner with Docker →

mail-tester shows “reverse DNS does not match”.

The PTR entry is missing, not propagated yet, or doesn’t match the A record. Set the PTR in the provider panel to mail.YOUR_DOMAIN, check with dig -x, and make sure the name points forward to the same IP.
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →

DKIM fails (DKIM: FAIL or “no signature”).

The DNS record was adopted incorrectly (genuinely truncated key, wrong selector) or not propagated yet. Copy the value exactly from the mail server UI, match the selector in the record (SELECTOR._domainkey) with the one configured in the server, then counter-check with dig. Two quoted blocks are normal there, see step 3.
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →

SPF “permerror” or “too many DNS lookups”.

Several SPF records, or too many nested include: (limit: 10 DNS lookups). Check with dig +short TXT YOUR_DOMAIN | grep spf1 that really only one line comes back, consolidate to one SPF record and remove unnecessary include:.
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →

Mails to Outlook/Hotmail land in spam or get rejected.

A hard rejection with 550 5.7.515 Access denied, sending domain … does not meet the required authentication level is not a reputation problem but Microsoft’s authentication rule from step 7. If the mails only land in the junk folder, Microsoft is simply strict with new IPs – only the warm-up from step 8 helps there.
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →

Your IP is on a block list.

The IP was with a spammer before you, or a mailbox of yours sends spam. Check on the common block-list checkers, and on a legitimate hit have it removed via the respective delisting form – and fix the cause (compromised account).
Read on: Email deliverability: SPF, DKIM, DMARC and PTR →

The web interface on port 8080 doesn’t respond.

The container is still booting or port 8080 is occupied/blocked. Check docker compose ps, read docker compose logs and make sure the firewall lets port 8080 (and later 443) through. If the log output stays completely empty after the setup, the log destination is still set to Log file. Switch it to Console in the console under Settings → Telemetry → Tracers and restart.
Read on: Stalwart: a lightweight mail server in one container →

The first sign-in fails with “Client metadata documents are disabled”.

You’re opening the setup wizard via HTTPS or your reverse proxy. As long as Stalwart is in bootstrap mode, signing in only works via http://…:8080/admin, directly via the IP or through an SSH tunnel to localhost:8080.
Read on: Stalwart: a lightweight mail server in one container →

Signing in fails with “Unknown client id”.

You’re opening the console via http://…:8080 or the IP address. After the setup, signing in only works at https://mail.YOUR_DOMAIN/admin, with the hostname from the wizard and over HTTPS.
Read on: Stalwart: a lightweight mail server in one container →

I missed the bootstrap password.

As long as the wizard isn’t finished, a docker compose restart is enough; Stalwart then logs a new one-time password. More permanently: set a STALWART_RECOVERY_ADMIN=admin:YOUR_PASSWORD under environment: in the compose.yaml and restart with docker compose up -d. That gives you a fixed recovery-admin account.
Read on: Stalwart: a lightweight mail server in one container →

No TLS certificate, the HTTPS address shows a warning.

Either Let’s Encrypt can’t reach your server on port 443 (Stalwart uses the TLS-ALPN-01 challenge over 443), or one of the five hostnames from step 1 is missing in DNS. The log names the culprit: ACME authentication error … NXDOMAIN looking up A for autoconfig.YOUR_DOMAIN. Add the missing records, open port 443 in the firewall; Stalwart retries the certificate request automatically afterwards.
Read on: Stalwart: a lightweight mail server in one container →

Mails to the outside stay stuck, logs show timeouts on port 25.

Your provider blocks outbound SMTP traffic. At netcup the default policy “netcup Mail block” (ports 25/465/587) is to blame: in the SCP under Firewall → Policies, take that netcup template off the server, no ticket needed, see netcup firewall setup. Without it, no delivery to other servers is possible.
Read on: Stalwart: a lightweight mail server in one container →

Other servers don’t accept your mails or they land in spam.

Missing or wrong PTR entry, no SPF/DKIM/DMARC. That’s not a Stalwart error but a matter of DNS/reputation configuration; see the email deliverability tutorial.
Read on: Stalwart: a lightweight mail server in one container →

The page answers with 403 Forbidden

(behind Traefik only). The lock from step 4 does not let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Your own mail server with Mailcow: setup from scratch →

The interface only shows Fatal error: … Failed opening required '/web/inc/app_info.inc.php'.

The generator ran without umask 0022, for example after a fresh SSH login or on a server whose default umask is stricter (027 after a Lynis hardening, say). The file then gets mode 640, and PHP inside the container can’t read it. chmod 644 data/web/inc/app_info.inc.php brings the page back immediately; the cleaner fix is to delete the folder and repeat step 3 in one session with umask 0022, so no other file is affected.
Read on: Your own mail server with Mailcow: setup from scratch →

generate_config.sh aborts with Cannot find command 'jq'.

The jq package is missing. sudo apt install -y jq and start the generator again.
Read on: Your own mail server with Mailcow: setup from scratch →

The generator reports “User declined to create daemon.json” and aborts.

On hosts with active IPv6 you answered the question about the IPv6-capable Docker configuration with n – without it mailcow won’t run there, and an open relay looms. Create /etc/docker/daemon.json containing {"ipv6": true} (Docker 28 and newer), restart Docker with sudo systemctl restart docker and run ./generate_config.sh again – or simply confirm the question with Enter on the second attempt, then the generator does both itself.
Read on: Your own mail server with Mailcow: setup from scratch →

The webmail only answers Unauthorized.

SOGo doesn’t know your mail domain: it reads the domain list exclusively at startup and wasn’t restarted after the domain was created – its logs say No authentication sources defined - nobody will be able to login. Restart SOGo via E-Mail → Restart SOGo. If that doesn’t help, a failed login is still stuck in the cache: docker compose restart memcached-mailcow sogo-mailcow.
Read on: Your own mail server with Mailcow: setup from scratch →

No certificate, acme-mailcow keeps restarting

(only without Traefik). Let’s Encrypt can’t reach your server on port 80, or the A record of mail.YOUR_DOMAIN is wrong. Check with docker compose logs acme-mailcow whether the hostname and IP match, and that port 80 is open through UFW and the netcup firewall.
Read on: Your own mail server with Mailcow: setup from scratch →

Mails to the outside aren’t delivered, logs show timeouts on port 25.

Your provider blocks outbound SMTP traffic (common as spam protection). At netcup it’s the default policy “netcup Mail block” (ports 25/465/587): in the SCP under Firewall → Policies, take that netcup template off the server – no support ticket needed, details in netcup firewall setup. Without it you can’t send mail to other servers – receiving and local delivery still work.
Read on: Your own mail server with Mailcow: setup from scratch →

Ports 80/443 can’t be bound (address already in use).

A web server or reverse proxy (e.g. Traefik) already runs on the host. Either mailcow gets a server of its own, or you put it behind the proxy as in step 4. The mail ports sit directly on the host either way.
Read on: Your own mail server with Mailcow: setup from scratch →

Behind Traefik the interface doesn’t load, the browser reports too many redirects.

mailcow.conf still says HTTP_REDIRECT=y. mailcow’s nginx then redirects even the requests Traefik passes on unencrypted to HTTPS – in a circle. Set HTTP_REDIRECT=n and run docker compose up -d.
Read on: Your own mail server with Mailcow: setup from scratch →

Behind Traefik, mail programs show a self-signed certificate.

The dumper wrote nothing or didn’t restart Postfix and Dovecot. docker compose logs certdumper tells you why: acme.json is not a file means a wrong path to Traefik’s directory. If there is no Restarting container … was successful, the names in --restart-containers are wrong – compare them with docker compose ps --format '{{.Name}}'.
Read on: Your own mail server with Mailcow: setup from scratch →

Containers start slowly or are killed by the kernel (OOM).

Too little RAM. Go to at least 6–8 GB or disable ClamAV in mailcow.conf (SKIP_CLAMD=y) – the virus scanner is the biggest memory eater.
Read on: Your own mail server with Mailcow: setup from scratch →

The app reports “Cannot connect” or the web client stays empty.

The NTFY_BASE_URL doesn’t match the called address. It must be exactly your public HTTPS URL (https://ntfy.YOUR_DOMAIN, without a trailing slash). After a change, run docker compose up -d again.
Read on: ntfy: push notifications to your phone →

curl returns HTTP 401 or 403.

With deny-all, missing or wrong credentials are the most common error. Check the user/password (docker exec ntfy ntfy user list) and, when sending, supply -u USER:PASSWORD or the bearer token. A 403 means the user exists but has no rights to this topic – then grant rights with ntfy access.
Read on: ntfy: push notifications to your phone →

Messages arrive in the browser but not as push on the phone when the tab is closed.

Browser push needs granted notification rights and an active service worker; that’s unreliable once the tab is closed. For real “on the go” push, use the ntfy app – it keeps the connection in the background.
Read on: ntfy: push notifications to your phone →

502 Bad Gateway from Traefik.

The container isn’t ready yet or listens on the wrong port. Check docker compose logs ntfy and that the label loadbalancer.server.port=80 is set – ntfy listens on port 80 in the container (NTFY_LISTEN_HTTP=":80").
Read on: ntfy: push notifications to your phone →

429 Too Many Requests with many messages in quick succession.

ntfy limits the rate per sender by default to prevent abuse. On a private server with your own scripts you rarely hit this – but a loop script without a pause does. Bundle messages instead of firing them every second, or raise the limits specifically via the NTFY_VISITOR_* environment variables (described in the ntfy docs under “Rate limiting”). NTFY_BEHIND_PROXY: "true" is a prerequisite so the limit applies per real IP instead of per Traefik container.
Read on: ntfy: push notifications to your phone →

The container writes, but the bind-mount folder on the host stays empty.

You used a relative path that points somewhere other than intended, or Docker created the path anew as an empty folder. With docker run, always give bind mounts an absolute path (/opt/app/config, not config). If this host path doesn’t exist yet, Docker silently creates it as an empty folder – so check with ls that you really hit the right one. In the compose.yaml, on the other hand, ./ paths are perfectly fine – they’re relative to the compose.yaml and thus unambiguous. Note also: docker run -v config:/data (without / or ./ in front) is not a bind mount, but creates a named volume called config.
Read on: Docker volumes vs. bind mounts: where data lives →

Permission denied as soon as the container tries to write into the mount.

The process in the container runs under a different UID than the owner of the host folder – typical with bind mounts. With named volumes this rarely happens (Docker sets the permissions). With bind mounts, give the folder to the matching user (chown -R 1000:1000 /opt/app/data) or set the UID the container runs under via the user: key in the compose.yaml.
Read on: Docker volumes vs. bind mounts: where data lives →

Docker volumes vs. bind mounts: After docker compose down all data is gone.

You used docker compose down -v – the -v deletes the named volumes too. For a normal restart, work without -v. Use -v deliberately only when you really want to start from scratch.
Read on: Docker volumes vs. bind mounts: where data lives →

docker system prune deleted data.

docker volume prune or docker system prune --volumes removes volumes that no container is currently attached to. With docker volume prune, named volumes are protected by default – only anonymous volumes are deleted; named ones only go with --all/-a. (With docker system prune, on the other hand, -a/--all controls the images, not the named volumes.) Another strong argument for naming – an sk-demo-vol survives an accidental docker volume prune, an anonymous volume doesn’t. Still, only run prune with volumes when all important stacks are active, or remove specifically with docker volume rm.
Read on: Docker volumes vs. bind mounts: where data lives →

Matomo: The page responds with 403 Forbidden.

The lock from step 3 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Self-hosting Matomo cookieless, without a banner →

The browser shows a certificate error or 404 page not found.

Traefik hasn’t fetched the Let’s Encrypt certificate yet, or the DNS record doesn’t point to the server. Check with dig stats.YOUR_DOMAIN that the IP is correct, and look at the Traefik logs. You find the exact container name from your Traefik setup with docker ps | grep traefik, then docker logs <container-name> (for us e.g. docker logs traefik-traefik-1). The HTTP challenge fails if port 80 isn’t reachable from outside – check your firewall and the netcup firewall.
Read on: Self-hosting Matomo cookieless, without a banner →

The installer reports SQLSTATE... Connection refused or hangs at the database.

MariaDB wasn’t ready on the first start. Give the DB a moment and reload the page. Check with docker compose logs db whether it says ready for connections. If an access error appears instead, the DB_PASSWORD in the .env and the already-created DB no longer match – then a clean restart with docker compose down -v (careful: deletes the data) and docker compose up -d helps.
Read on: Self-hosting Matomo cookieless, without a banner →

Warning “It looks like the trusted_hosts setting is not correct”.

Matomo checks, for security reasons, under which hostname it’s called. The warning appears when you change the domain. Confirm the correct hostname via the button in the message – Matomo then enters it in config/config.ini.php.
Read on: Self-hosting Matomo cookieless, without a banner →

No visits appear in the dashboard.

The tracking code is missing, incorrectly embedded, or you’re visiting your own site (Matomo ignores you if your IP is excluded). Open your website in a private window and check in the network tab whether a request to matomo.php goes out. In Matomo, Administration → Diagnostic → Tracking failures helps.
Read on: Self-hosting Matomo cookieless, without a banner →

The dashboard loads very slowly.

The on-the-fly archiving computes on every call. Set up the archiving cron from step 8 and switch report generation to cron.
Read on: Self-hosting Matomo cookieless, without a banner →

The container restarts repeatedly (Restarting), the log says bind: address already in use.

Forgejo’s built-in SSH server wants to listen on port 22, which the bundled OpenSSH service inside the container already occupies. Set SSH_PORT and SSH_LISTEN_PORT both to the same value (here 2222) – then Forgejo starts cleanly.
Read on: Forgejo: your own Git server behind Traefik →

The container takes forever to become healthy.

By default, Docker runs the first healthcheck only after the interval (30 s) – so the container looks “unhealthy” for 30 s+, even though Forgejo has long been ready in ~2 s. The solution is already in the Compose above: start_interval: 2s checks every 2 seconds during the startup phase and switches to healthy as soon as the app responds. (Requires Docker 25+ / Compose v2.20+ – given on Debian 13.)
Read on: Forgejo: your own Git server behind Traefik →

Forgejo: Traefik returns 502 Bad Gateway.

Almost always the wrong port: Forgejo’s web interface listens internally on 3000, so loadbalancer.server.port=3000 must be set and the container must be on the proxy network.
Read on: Forgejo: your own Git server behind Traefik →

Clone links show localhost or the wrong port.

Then ROOT_URL, SSH_DOMAIN or SSH_PORT are wrong. Correct the values in the Compose and restart with docker compose up -d.
Read on: Forgejo: your own Git server behind Traefik →

SSH clone fails with Permission denied (publickey).

The SSH server is running, but your public key isn’t stored in the account yet (step 6) – or you forgot the port 2222.
Read on: Forgejo: your own Git server behind Traefik →

HitKeep: The page responds with 403 Forbidden.

The lock from step 2 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: HitKeep: self-host privacy-friendly web analytics →

The live verifier stays on “Waiting” / no hits in the dashboard.

Check in the browser (dev tools → Network) whether hk.js is loaded at all and the send request afterwards comes back with status 2xx. Most common causes: the snippet isn’t in the HTML, the site domain created in HitKeep doesn’t match the hostname of the visited page, or an ad/tracking blocker filters the call. Since you host under your own domain (first-party), most blockers don’t apply – but some lists know the path hk.js.
Read on: HitKeep: self-host privacy-friendly web analytics →

All visitors seemingly come from a single IP, country and provider show “(Unknown)”.

Then HITKEEP_TRUSTED_PROXIES isn’t taking effect: the range you gave doesn’t contain your proxy’s IP, and HitKeep only evaluates Traefik’s container IP. Check which subnet the proxy sits in with docker network inspect proxy – 172.16.0.0/12 covers the usual Docker networks – and restart the stack (docker compose up -d). After that the real client IP from the X-Forwarded-For header counts again.
Read on: HitKeep: self-host privacy-friendly web analytics →

Traefik returns 404 or 502.

A 404 usually means the router rule isn’t matching – check that Host(...) contains your real domain and the container is on the proxy network. A 502 indicates the wrong port: HitKeep listens internally on 8080, so loadbalancer.server.port=8080 must be set.
Read on: HitKeep: self-host privacy-friendly web analytics →

After login you land on the login page again (login loop).

That’s almost always a mismatch in HITKEEP_PUBLIC_URL: the value must match exactly the address through which you call HitKeep (including https://, without a trailing slash). Correct the variable and restart the container.
Read on: HitKeep: self-host privacy-friendly web analytics →

The container won’t start or isn’t healthy.

Look at the logs: docker compose logs -f hitkeep. A missing or empty HITKEEP_JWT_SECRET is a typical start blocker – generate one as in step 1 and enter it.
Read on: HitKeep: self-host privacy-friendly web analytics →

A latest handshake never appears in wg show.

The UDP port isn’t reachable or the keys don’t match. WireGuard is silent with wrong keys – there’s no error message, just no handshake. Check: sudo ufw status (port 51820/udp open?), the netcup firewall (inbound UDP 51820), the Endpoint in the client (correct public IP?) and that the private and public keys aren’t swapped.
Read on: WireGuard VPN: secure access to your own server →

Handshake is there, but no internet arrives in the full tunnel.

Almost always the routing/NAT. Is net.ipv4.ip_forward=1 set (sysctl net.ipv4.ip_forward)? If Docker is running – or UFW is active – the FORWARD DROP trap from the warning box above applies; the most common mistake then is a missing RELATED,ESTABLISHED rule, i.e. a blocked return path. Check with sudo iptables -S FORWARD that both PostUp rules really are in the chain. Is the external interface in the MASQUERADE correct (eth0 vs. something else)?
Read on: WireGuard VPN: secure access to your own server →

Full tunnel is up, but curl -s ifconfig.me shows your own address.

If it is an IPv6 address, ::/0 is missing from the client’s AllowedIPs – IPv6 then bypasses the tunnel (IPv6 leak). Add it, restart the tunnel and check with curl -4 and curl -6 separately.
Read on: WireGuard VPN: secure access to your own server →

Full tunnel is up, but DNS queries still run past the tunnel (DNS leak).

Without a DNS = line, your device keeps querying the DNS servers of your local network – on open Wi-Fi the operator still sees which domains you visit. On Linux, check with resolvectl status which DNS server is assigned to the wg0 interface, or run a leak test (e.g. on dnsleaktest.com): if foreign resolvers appear there, enter a real resolver in the client config (DNS = 1.1.1.1) – or the server itself (10.8.0.1) if a dedicated DNS resolver runs there.
Read on: WireGuard VPN: secure access to your own server →

The tunnel is up, but large transfers (SSH, HTTPS, downloads) hang or break off.

An MTU problem. wg-quick sets the MTU to 1420; in some networks (DS-Lite, certain mobile networks) that’s still too high. Try MTU = 1412 or 1280 in the [Interface] section of the client.
Read on: WireGuard VPN: secure access to your own server →

wg-quick up reports resolvconf: command not found.

The DNS = line needs resolvconf. Either install sudo apt install openresolv or remove the DNS line if you don’t need the VPN DNS.
Read on: WireGuard VPN: secure access to your own server →

The connection falls asleep as soon as the phone briefly sends nothing.

The client sits behind NAT/CGNAT. PersistentKeepalive = 25 in the client config keeps the connection open.
Read on: WireGuard VPN: secure access to your own server →

Your figures are well below ours, especially for the CPU.

A VPS shares the physical CPU. Check the steal time (vmstat 1, column st) and top (line %st). If it’s persistently high, neighbors on the same host are computing right now. Measure again at a different time of day, often the difference is gone then.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →

The disk figures are absurdly high (e.g. “10 GB/s random read”).

There are two causes and you have to rule out both. Either --direct=1 is missing, in which case fio measures the page cache in RAM instead of the NVMe. Or you’re measuring in /tmp. On Debian 13 that’s a tmpfs and lives entirely in RAM, against which --direct=1 is powerless either; this mistake showed us 913,000 instead of 101,000 IOPS, almost nine times as much. Check with findmnt --target . -no FSTYPE what you’re measuring on: if it says tmpfs instead of ext4, switch to a directory on the real disk such as /var/tmp.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →

lsblk shows ROTA=1 (“rotational”) for vda in the column – is that a hard disk instead of NVMe?

No. That’s a virtualization artifact: the virtio driver reports the virtual disk as rotational across the board. The measured 100k+ IOPS and 4 GB/s prove that real flash storage is behind it.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →

The download is much slower than 2 Gbit/s.

Measure against a nearby, fast server (e.g. Falkenstein). A distant target or a slow counterpart limits the measurement, not your VPS. A single curl stream also doesn’t always exhaust the full bandwidth.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →

Every run delivers different numbers.

Normal, benchmarks fluctuate. Measure multiple times, discard the first run as a warm-up run and take the median of the rest. For us that very first run was off by a factor of three on the write test. Also compare only the same tool versions and parameters with each other.
Read on: netcup VPS 1000 G12 benchmarked: how fast is it really? →

docker compose pull pulls no new image, even though a new version exists.

Your tag points to a fixed version (:1.37.2) or to a major tag (:18), under which there’d only be a new major. pull only fetches what the same tag now points to. For a version jump you have to bump the tag in the compose.yaml yourself.
Read on: Keeping your whole Docker stack safely up to date →

The app no longer starts after the update or throws database errors.

Usually a breaking change or a failed migration. Check docker compose logs, compare with the release notes. Set the tag back to the old version and up -d; if the new version already migrated the data, restore the backup from step 3.
Read on: Keeping your whole Docker stack safely up to date →

Diun reports nothing, even though updates exist.

Check that the containers carry the label diun.enable=true and Diun can read the socket (DIUN_PROVIDERS_DOCKER=true, socket mounted). For newer version tags the container additionally needs diun.watch_repo=true – without it, Diun only sees changes to the exactly pinned tag. And: whatever Diun sees for the first time is only written to the database, not reported (watch.firstCheckNotif is false) – to test the notification path, set DIUN_WATCH_FIRSTCHECKNOTIF=true once.
Read on: Keeping your whole Docker stack safely up to date →

The disk fills up, even though you regularly run docker image prune.

docker image prune only clears dangling images, not the old tagged versions. Remove them specifically with docker rmi <image>:<tag> or – with care – docker image prune -a. The build cache (docker builder prune) can grow too.
Read on: Keeping your whole Docker stack safely up to date →

On pulling you get toomanyrequests / a Docker Hub rate limit.

diun.watch_repo=true on many images queries many tags. Set the watch interval less often (e.g. once daily) and narrow with diun.include_tags to relevant versions instead of scanning the whole repo.
Read on: Keeping your whole Docker stack safely up to date →

A freshly set ban doesn’t take effect, the IP keeps getting 200.

Wait up to a minute – the bouncer only fetches new decisions after the pull interval (step 4).
Read on: CrowdSec: modern, collaborative intrusion prevention →

cscli metrics show acquisition shows no line for the log file.

CrowdSec isn’t reading the logs. Most common cause: the container started before the access.log existed (No matching files for pattern … in docker logs crowdsec, see step 1) – cd ~/crowdsec && docker compose restart fixes it. Otherwise check that Traefik really writes to /var/log/traefik/access.log, that both containers mount the same host path, and that the acquis.yaml names exactly this path.
Read on: CrowdSec: modern, collaborative intrusion prevention →

After restarting Traefik every app returns 403 – including for you.

The bouncer can’t reach the LAPI; the Traefik log says crowdsecQuery:unreachable with the URL http://crowdsec:8080/v1/decisions/stream. Check with docker ps that the crowdsec container is Up – as soon as the next pull succeeds, requests go through again on their own (background in the box in step 3).
Read on: CrowdSec: modern, collaborative intrusion prevention →

CrowdSec bans lots of harmless or no real visitors – the detected IP is always your CDN’s.

If a CDN like Cloudflare sits in front of Traefik, Traefik only sees its IP. Then have the real client IP read from the X-Forwarded-For header: fill forwardedHeadersTrustedIPs in the middleware with the CDN networks – otherwise you end up banning the CDN. Directly at netcup (without a CDN) there’s nothing to do here.
Read on: CrowdSec: modern, collaborative intrusion prevention →

docker compose up -d on Traefik reports a plugin error.

Traefik downloads the plugin from the net on startup. Check that the server may go out (the netcup firewall only blocks SMTP outbound, UFW nothing) and that modulename and version are exactly right.
Read on: CrowdSec: modern, collaborative intrusion prevention →

CrowdSec bans nothing even though the attacks are in access.log – or it bans 172.18.0.1.

Then Traefik never sees the real source address in the first place. This happens with IPv6 visitors when the proxy network was created without IPv6: Docker then replaces the source address with the bridge gateway’s, every IPv6 request carries the same 172.x.x.x in access.log, and a ban on that either hits nobody or everybody. Recreate the network with --ipv6; the instructions are in Reverse proxy with Traefik.
Read on: CrowdSec: modern, collaborative intrusion prevention →

dd overwrote the wrong disk – data gone.

dd doesn’t ask and isn’t mockingly called “disk destroyer” for nothing. Check the target (of=) always beforehand with lsblk, and never confuse sda with sdb. There’s no undo – when in doubt, read it three times.
Read on: The essential terminal commands for your server →

kill -9 ended a service, but the database is corrupted afterwards.

-9 gives the process no chance to close cleanly. Always first use kill without -9 and give the process a few seconds. Only when it really hangs does the hard variant follow.
Read on: The essential terminal commands for your server →

rsync copied (or deleted) much more than expected.

The trailing slash decides: rsync -a /source/ copies the contents of source, rsync -a /source copies the folder along with it. And --delete deletes everything in the target that’s missing in the source. Test with -n first, always.
Read on: The essential terminal commands for your server →

A tool reports “command not found”.

The package isn’t installed. Install it (see tip box above) or check the name. Some tools like iotop additionally need sudo to see any data at all.
Read on: The essential terminal commands for your server →

After tmux, on the next login “everything is gone”.

You started a new session instead of attaching. tmux ls lists running sessions, tmux attach -t 0 attaches you to the first. Just tmux on its own creates a fresh one every time.
Read on: The essential terminal commands for your server →

A target is at up = 0 or “DOWN” in Prometheus.

Prometheus can’t reach the exporter. For cadvisor, check that it’s on the same monitoring network and the name and port are exactly right (cadvisor:8080). For the node job, check the extra_hosts entry on the Prometheus service and the target host.docker.internal:9100 – without both, Prometheus doesn’t find the node-exporter in the host network. After changes to the prometheus.yml, restart the Prometheus container: docker compose restart prometheus.
Read on: Monitoring with Grafana & Prometheus: live dashboards →

The cAdvisor dashboard partly shows “No data” or cAdvisor won’t start.

If the mounts or privileged: true are missing, cAdvisor doesn’t see the containers. Check the cadvisor block (mounts, devices: /dev/kmsg). Individual “No data” panels are normal – some metrics (like CPU throttling) only exist if you’ve set CPU limits on the containers.
Read on: Monitoring with Grafana & Prometheus: live dashboards →

Grafana doesn’t load correctly behind Traefik – login fails or the layout is broken.

Almost always GF_SERVER_ROOT_URL is wrong. It must be exactly the public address (https://grafana.YOUR_DOMAIN). Also check that the Traefik label loadbalancer.server.port=3000 is set – Grafana listens on 3000 internally.
Read on: Monitoring with Grafana & Prometheus: live dashboards →

Grafana shows “No data” in the panels, even though the targets are up.

Usually the time range. A fresh stack has no history yet – set “Last 15 minutes” at the top right and wait a few minutes for data to accumulate. Also check that the Prometheus data source was selected on dashboard import.
Read on: Monitoring with Grafana & Prometheus: live dashboards →

Prometheus won’t start and its log says permission denied for prometheus.yml.

The server is hardened (UMASK 027) and Prometheus isn’t allowed to read its configuration. Fix it with chmod 644 prometheus/prometheus.yml from step 3 and docker compose restart prometheus. If the data source is missing in Grafana, the same applies to datasource.yml.
Read on: Monitoring with Grafana & Prometheus: live dashboards →

The disk space on the server grows steadily.

That’s the Prometheus TSDB. Reduce --storage.tsdb.retention.time (e.g. to 15d) or monitor fewer targets. The prom_data volume grows with the number of metrics × retention time.
Read on: Monitoring with Grafana & Prometheus: live dashboards →

Jellyfin: The page answers with 403 Forbidden.

The restriction from step 4 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Self-hosting Jellyfin: your own media server →

502 Bad Gateway on access, even though the container is running.

Traefik reaches the container but hits the wrong port. Jellyfin listens on 8096 – check the label traefik.http.services.jellyfin.loadbalancer.server.port=8096 for typos. If a 504 Gateway Timeout comes back after a few seconds instead, the port isn’t the problem, the network is: then networks: [proxy] is missing and Traefik is running against an address it can’t reach at all.
Read on: Self-hosting Jellyfin: your own media server →

The libraries stay empty, even though files are there.

Almost always a permission problem. The container runs as 1000:1000 (step 4), so the media must belong to that user: sudo chown -R 1000:1000 /mnt/media. And: in Jellyfin the container path must be entered (/media/filme), not the host path. Afterwards click “Scan All Libraries” at the top of the Dashboard – under Scheduled Tasks the same job is called “Scan Media Library”.
Read on: Self-hosting Jellyfin: your own media server →

Video stutters/buffers, docker stats shows Jellyfin at ~100% CPU.

It’s transcoding. Under Dashboard → Playback the activity monitor shows whether it says “Transcode” instead of “Direct Play”. Set the client quality to original, change exotic codecs to a widely supported format, or give the server more (dedicated) cores.
Read on: Self-hosting Jellyfin: your own media server →

After a reboot the library is gone and Jellyfin shows empty folders.

The block storage wasn’t mounted – usually a missing or wrong fstab entry (step 2). Check with df -h /mnt/media and sudo mount -a. The line must use the UUID, not /dev/vdb1.
Read on: Self-hosting Jellyfin: your own media server →

The login page loads, but the app can’t find the server / links point to an internal address.

JELLYFIN_PublishedServerUrl is missing or wrong. Set it in the compose.yaml to https://jellyfin.YOUR_DOMAIN and restart with docker compose up -d (a restart isn’t enough for the environment change to take effect).
Read on: Self-hosting Jellyfin: your own media server →

Immich: The page answers with 403 Forbidden.

The restriction from step 3 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Self-hosting Immich: your private photo backup →

Uploads of large videos abort after about a minute (error 502 or 499).

Traefik’s readTimeout (default 60 s) kicks in. Set it to 600s (or higher) as in step 4 and restart Traefik. This is by far the most common Immich-behind-proxy error.
Read on: Self-hosting Immich: your private photo backup →

The immich-machine-learning container crashes or exits with “exit 137”, search and face recognition don’t work.

Too little RAM – the container was killed by the system (out of memory). Give the server more memory, or disable ML by removing the service immich-machine-learning from the compose.yaml. Immich then runs without face recognition and smart search, but upload and timeline work normally.
Read on: Self-hosting Immich: your private photo backup →

After an update the containers no longer start or report migration errors.

Server, machine learning and database must run on the same version. Set the new IMMICH_VERSION in the .env and update all containers together (docker compose pull && docker compose up -d). A downgrade after a migration isn’t possible – only a reset from the backup.
Read on: Self-hosting Immich: your private photo backup →

Immich shows “maintenance mode” / “temporarily unavailable”.

Immich v3 starts into a maintenance mode under certain database states. The log (docker compose logs immich-server) then contains a URL with a one-time token (…/maintenance?token=…) – through it you log into the maintenance mode and choose “restart” or end it. After that the normal interface is back.
Read on: Self-hosting Immich: your private photo backup →

Container won’t start, “permission denied” on the database or upload directory.

UPLOAD_LOCATION or DB_DATA_LOCATION have the wrong access rights or are on a network drive. Put both on a local disk and make sure Docker may write into them.
Read on: Self-hosting Immich: your private photo backup →

On login, “Forbidden (403)” or “CSRF verification failed” appears.

PAPERLESS_URL is not set or set wrong. It must exactly match your HTTPS address (https://paperless.YOUR_DOMAIN, without a trailing slash). After the correction, docker compose up -d.
Read on: Self-hosting Paperless-ngx: the paperless office →

Files in the consume folder aren’t processed, “permission denied”.

Most common cause: the folders weren’t created beforehand (step 3), but generated by the Docker daemon on the first start – then they belong to root. With sudo chown -R $(id -u):$(id -g) ~/paperless/consume ~/paperless/export they belong to you again. Otherwise: USERMAP_UID/USERMAP_GID don’t match the folder’s owner – determine your ID with id -u and id -g, enter the values and restart.
Read on: Self-hosting Paperless-ngx: the paperless office →

Uploaded documents get stuck “in processing”.

The background processing runs via the broker. Check that the broker container is running, and look under Tasks for the error message of the failed task. If the broker keeps showing Restarting and its log says Can't handle RDB format version 15, you attached a Redis volume to Valkey – see “Still running Redis?” under maintenance.
Read on: Self-hosting Paperless-ngx: the paperless office →

Text recognition returns gibberish or recognizes nothing.

Wrong OCR language. Set PAPERLESS_OCR_LANGUAGE=eng (or eng+deu for mixed documents). Only installed languages work.
Read on: Self-hosting Paperless-ngx: the paperless office →

Office documents (Word, Excel) aren’t accepted or end in a timeout.

Gotenberg and Tika are responsible for those. Check that both containers are running and PAPERLESS_TIKA_ENABLED=1 plus the two endpoint variables are set.
Read on: Self-hosting Paperless-ngx: the paperless office →

During bulk import the server gets very slow, the CPU is constantly maxed out.

OCR is compute-intensive, and Paperless uses all cores by default. On small servers you can throttle the load by limiting the number of workers or threads (PAPERLESS_TASK_WORKERS, PAPERLESS_THREADS_PER_WORKER). Then the import takes longer, but the interface stays usable.
Read on: Self-hosting Paperless-ngx: the paperless office →

After the Traefik restart, the HSTS header doesn’t appear in the curl output.

Usually the middleware isn’t on the router. Check that the line traefik.http.routers.nc.middlewares names both middlewares (nc-dav,nc-secure) and that the two nc-secure header labels are in the nc-app block. Then docker compose up -d nc-app. Traefik only picks up changed labels when recreating the container.
Read on: Hardening & optimizing Nextcloud (Part 2) →

The email test fails (“There was a problem sending the email”).

Almost always port/encryption or authentication. Combine SSL/TLS with port 465 or None / STARTTLS with port 587, not crosswise. If your provider uses 2FA, you need an app password (see step 4). Details are in the Nextcloud log: docker exec -u www-data nc-app php occ log:tail 20.
Read on: Hardening & optimizing Nextcloud (Part 2) →

You can’t get in yourself after enforcing 2FA.

You hadn’t set up a second factor yet. Lift the requirement via the command line, set up your factor calmly and arm it again afterwards: docker exec -u www-data nc-app php occ twofactorauth:enforce --off.
Read on: Hardening & optimizing Nextcloud (Part 2) →

In the brute-force box a 172.x.x.x address appears instead of your real IP.

TRUSTED_PROXIES doesn’t match the actual proxy subnets. Print both of them – the network has an IPv6 and an IPv4 range – and enter them space-separated in the nc-app environment (part 1, step 2): docker network inspect proxy -f '{{ range .IPAM.Config }}{{ .Subnet }} {{ end }}'. Otherwise the brute-force protection bans the proxy in an emergency and thus all users.
Read on: Hardening & optimizing Nextcloud (Part 2) →

After a reboot, Nextcloud reports “Redis went away” or gets very slow.

The app container started before Redis. Make sure nc-redis is in depends_on (part 1) and runs with restart: unless-stopped – then Docker catches the start-order case itself.
Read on: Hardening & optimizing Nextcloud (Part 2) →

Nextcloud: The page answers with 403 Forbidden.

The restriction from step 3 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →

“Access through untrusted domain” instead of the login page.

Your domain isn’t in trusted_domains. Check NEXTCLOUD_TRUSTED_DOMAINS in the Compose file. To set it afterwards, use occ: docker exec -u www-data nc-app php occ config:system:set trusted_domains 1 --value=cloud.YOUR_DOMAIN.
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →

The security check reports “Your web server is not set up properly to resolve .well-known/caldav”.

The CalDAV/CardDAV redirect isn’t working. Check the nc-dav middleware labels (step 3) and that the router includes them via ...routers.nc.middlewares=nc-dav. The regex must match the full https://… URL – redirectregex checks the complete URL, not just the path.
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →

Warning “The ‘Strict-Transport-Security’ HTTP header is not set”.

The HSTS header is missing. Set it as a Traefik middleware and attach it to the router: traefik.http.middlewares.nc-secure.headers.stsSeconds=15552000. Attach it additionally to the nc-dav middleware on the router (...routers.nc.middlewares=nc-dav,nc-secure). The header must come from the proxy, not from Nextcloud. In part 2 we set up exactly this nc-secure middleware fully (including includeSubdomains).
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →

Large uploads break off or end with a timeout / “413”.

The PHP limit is too small. Increase PHP_UPLOAD_LIMIT and PHP_MEMORY_LIMIT (step 3) and restart the container. In rare cases these variables don’t take effect – then mount your own php.ini snippet into the image.
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →

On the first start the installation aborts with “MySQL server has gone away” or “Connection refused”.

The app container was faster than the database. That’s exactly what the healthcheck with depends_on: condition: service_healthy is for – check that both are present in your Compose file, and restart with docker compose up -d.
Read on: Self-hosting Nextcloud: your own cloud behind Traefik →

Uptime Kuma: The page responds with 403 Forbidden.

The lock from step 1 doesn’t let your address through. Usually the IPv6 is missing or has changed – look up both addresses again (see there), correct sourcerange and restart with docker compose up -d.
Read on: Uptime Kuma: server monitoring behind Traefik →

Bad Gateway (502) when opening status.YOUR_DOMAIN.

Almost always the port label traefik.http.services.kuma.loadbalancer.server.port=3001 is missing or has a wrong port. Traefik then reaches the container but knocks on the wrong port. Check the label and run docker compose up -d again.
Read on: Uptime Kuma: server monitoring behind Traefik →

404 page not found instead of Kuma.

As with every app behind Traefik: traefik.enable=true set? Container on the proxy network? Is the domain in the Host(...) rule correct and does the DNS record status.YOUR_DOMAIN point to the server? The Traefik dashboard shows under “HTTP Routers” whether kuma is registered.
Read on: Uptime Kuma: server monitoring behind Traefik →

The interface loads, but the live update stutters / breaks off.

Kuma uses WebSockets. Traefik forwards those correctly by default – if the problem still occurs, it’s usually an upstream CDN/proxy (e.g. Cloudflare in “proxy” mode) that blocks WebSockets. For direct operation behind Traefik, no extra configuration is needed.
Read on: Uptime Kuma: server monitoring behind Traefik →

After a re-setup all monitors are gone.

The kuma-data volume was deleted (e.g. by docker compose down -v). All configuration and history lives solely in this volume – that’s why it’s at the top of the next section.
Read on: Uptime Kuma: server monitoring behind Traefik →

The container exits again immediately, the log says No persistent volume!.

The volumes: mapping is missing. Vaultwarden then aborts with the box “It looks like you did not configure a persistent volume!” and exits with code 1, so your passwords don’t end up in an ephemeral container. Add ./vw-data:/data as in step 2 and restart.
Read on: Vaultwarden: your own password manager behind Traefik →

The web interface shows “You need to enable HTTPS!” or the login fails with crypto errors.

Vaultwarden uses the browser’s Web Crypto API, which is only available in a secure context (real HTTPS). You opened the page over http:// or with an invalid certificate. Make sure Traefik fetched a valid Let’s Encrypt certificate (check the Traefik log) and that you reach the page over https://. The DOMAIN variable must also start with https://.
Read on: Vaultwarden: your own password manager behind Traefik →

The admin panel rejects your password, even though it’s correct.

Probably the dollar signs in the ADMIN_TOKEN aren’t doubled. In the compose.yaml every $ must become $$. Check with docker compose exec vaultwarden printenv ADMIN_TOKEN how the token really arrives inside the container – there it has to be a single $ again. (docker compose config won’t help: it shows the file with the doubled $$.) Also remember: at login you enter the password, not the hash.
Read on: Vaultwarden: your own password manager behind Traefik →

The phone app can’t find the server or reports “Server URL invalid”.

The server URL must be the full https:// address without a trailing path (https://vault.YOUR_DOMAIN). Also check whether the domain is reachable from outside via a browser and the certificate is valid – apps are stricter about certificate errors than browsers.
Read on: Vaultwarden: your own password manager behind Traefik →

Despite SIGNUPS_ALLOWED=false, someone was able to register.

The setting was probably set in the admin panel and overrides the environment variable, or the container wasn’t restarted after the change. Check the value under Settings → General settings in the panel and restart with docker compose up -d.
Read on: Vaultwarden: your own password manager behind Traefik →

The dry run reports No packages found that can be upgraded unattended.

Usually perfectly normal – no security update is currently pending. Check the configuration anyway via the Allowed origins are: line in the --debug run. If no security origins appear there, the Origins-Pattern from step 3 isn’t right.
Read on: Automatic security updates with unattended-upgrades →

Updates come, but the server never reboots despite a kernel update.

Usually Automatic-Reboot is set to "false" (default) – then set it to "true" and give it an Automatic-Reboot-Time (step 3). If the option is right, check the marker file: without /var/run/reboot-required the reboot never triggers. The package’s kernel hook is what sets it – dpkg -S /etc/kernel/postinst.d/unattended-upgrades must report it (step 3).
Read on: Automatic security updates with unattended-upgrades →

/boot fills up, updates fail.

Old kernels pile up. Set Remove-Unused-Kernel-Packages "true" (step 3); clean up once with sudo apt autoremove --purge.
Read on: Automatic security updates with unattended-upgrades →

A package is stubbornly held back (kept back).

unattended-upgrades doesn’t install updates that would remove other packages. You resolve such cases deliberately by hand with sudo apt upgrade and check what happens.
Read on: Automatic security updates with unattended-upgrades →

You locked yourself out.

ignoreip was missing or contained the wrong IP. Connect via the console in the netcup SCP (independent of SSH) and unban yourself with sudo fail2ban-client set sshd unbanip YOUR_OWN_IP. Then enter your IP in ignoreip and reload. That’s why the whitelist comes first in step 2.
Read on: Fail2ban: block brute-force attacks automatically →

fail2ban.service won’t start (systemctl status shows “failed”).

Almost always a typo in jail.local. Check the syntax with sudo fail2ban-client -t (test mode) – the command names the faulty line.
Read on: Fail2ban: block brute-force attacks automatically →

Your values from jail.local don’t take effect.

Bans only last 10 minutes, or your own IP gets thrown out despite ignoreip. Almost always the reload is missing – the service was already running before you wrote your first own line, and start/enable --now does nothing on a running service. What actually applies is shown by sudo fail2ban-client get sshd bantime (600 = Debian default, 3600 = your hour) and sudo fail2ban-client get sshd ignoreip; it is applied with sudo systemctl reload fail2ban.
Read on: Fail2ban: block brute-force attacks automatically →

No one is ever banned, even though the log is full of failed attempts.

Check with sudo fail2ban-client status sshd whether Total failed rises at all. If it stays at 0, the filter isn’t finding the entries – usually because an outdated guide set a logpath to a non-existent file. On Debian 13, remove the logpath from jail.local and use the journal (step 2).
Read on: Fail2ban: block brute-force attacks automatically →

Bans “don’t work” – the IP keeps connecting.

On Debian 13, Fail2ban bans via nftables (banaction = nftables from defaults-debian.conf). You can see it with sudo nft list table inet f2b-table: it holds the chain f2b-chain and inside it an address set addr-set-sshd with the banned IPs. sudo iptables -L -n | grep f2b, on the other hand, returns nothing – that’s not a fault but the wrong tool layer, where older guides get stuck. If the table is missing entirely, the interplay with the firewall is stuck – restart the service and look at /var/log/fail2ban.log.
Read on: Fail2ban: block brute-force attacks automatically →

subprocess ssh: Host key verification failed with the SFTP target.

Restic can’t confirm the SSH host key of the backup server because it isn’t known yet. Connect once manually (ssh BACKUP_USER@YOUR_BACKUP_HOST) and confirm the fingerprint – or store it with ssh-keyscan YOUR_BACKUP_HOST >> ~/.ssh/known_hosts. After that Restic runs through.
Read on: Restic backups: encrypted and off-site →

wrong password or repository does not exist.

RESTIC_REPOSITORY or RESTIC_PASSWORD_FILE isn’t set or points nowhere – so check the EnvironmentFile in the systemd service. A manually set export only applies in the current shell.
Read on: Restic backups: encrypted and off-site →

repository is already locked.

An aborted run left a lock. Check that really no backup is running anymore, then restic unlock. Never unlock blindly while a run is active in parallel.
Read on: Restic backups: encrypted and off-site →

The backup gets huge / backs up nonsense.

Restrict it with --exclude/--exclude-file (caches, logs, temporary files) and use --one-file-system so Restic doesn’t dive into mounted foreign filesystems.
Read on: Restic backups: encrypted and off-site →

prune takes forever or was aborted.

No reason to panic – prune is resumable and the repository stays valid. Start it again and afterwards run restic check once. Separate --prune from the daily backup on large repos (see step 6).
Read on: Restic backups: encrypted and off-site →

The timer runs, but a success message never arrives in Uptime Kuma.

Look at the last run with journalctl -u restic-backup.service. Usually the script aborts before the curl call (e.g. the DB dump failed) – thanks to set -euo pipefail it then stops cleanly instead of reporting a broken backup as success. So the missing push isn’t a bug, but exactly the alarm signal you want.
Read on: Restic backups: encrypted and off-site →

“Certificate invalid” in the browser, or the Traefik log shows ACME errors.

The three usual reasons: (1) The DNS record doesn’t point to the server yet – check dig +short YOUR_DOMAIN. (2) Port 80 isn’t reachable from outside (firewall/netcup firewall) – the HTTP challenge needs it. (3) You hit the rate limit of the production CA – switch to the staging server (tip in step 3), test, then go back.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

404 page not found when calling the app domain.

Traefik doesn’t know the route. Check: Does the container have traefik.enable=true? Is it on the proxy network? Is the domain in the Host(...) rule exactly right (incl. subdomain)? The dashboard (step 7) shows under “HTTP Routers” whether the router was registered.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

The browser shows Traefik’s self-signed emergency certificate; the log reads permissions 644 for /acme.json are too open, please use 600.

Traefik is running but skipped the ACME resolver – hence no real certificate. Run chmod 600 acme.json (step 2) and restart the container.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

No app is routed; the Traefik log repeats client version 1.24 is too old. Minimum supported API version is 1.40.

Your Traefik version is too old for your Docker engine – the Docker provider can no longer query the socket. Current Docker (Engine 29, API level ≥ 1.40) needs Traefik ≥ v3.6; that’s why this tutorial uses traefik:v3.7. Reproduced against Docker 29: v3.5.6 runs into exactly this error, v3.6.25 talks to the socket cleanly again. So older tags like v3.3 or v3.5 no longer work with new Docker – bump the image tag and run docker compose up -d again.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

Basic auth on the dashboard is rejected immediately / the router is missing.

In the compose.yaml, the $ characters of the hash must be doubled ($$). Check the hash once more outside with htpasswd -nbB.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

Gateway Timeout or Traefik doesn’t reach the container.

Usually the app is on the wrong network, or Traefik doesn’t know which one is meant. providers.docker.network=proxy in Traefik and networks: [proxy] on the app must match.
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

502 Bad Gateway, even though the container is running.

Traefik reaches the container but hits the wrong port. If the app doesn’t listen on 80, it needs the label traefik.http.services.<name>.loadbalancer.server.port=<real-port>. This exact case meets you with the first app in the next tutorial (Uptime Kuma on 3001).
Read on: Setting up Traefik: reverse proxy with automatic HTTPS →

dig returns no IP or a wrong (old) one.

Usually still propagation. Query a public resolver specifically to bypass your local cache: dig +short YOUR_DOMAIN @1.1.1.1. If it already shows the correct value, only your local/provider cache hasn’t expired yet – wait.
Read on: Connecting a domain to your server (DNS basics) →

The domain resolves, but to the wrong IP – e.g. a registrar’s parking page.

Often an old A record or a redirect/parking setting still exists. Remove contradictory entries; per name and type there should be exactly one value (deliberate exceptions aside).
Read on: Connecting a domain to your server (DNS basics) →

IPv4 works, IPv6 (AAAA) leads to timeouts.

You entered an AAAA record even though the server has no working IPv6 address. Browsers then prefer IPv6 and run into a timeout. Remove the AAAA record until the server really supports IPv6.
Read on: Connecting a domain to your server (DNS basics) →

In some interfaces the value is stored with a trailing dot (YOUR_DOMAIN.) and you’re unsure.

The trailing dot (root of the DNS hierarchy) is normal and correct – many DNS managers add it automatically. No reason to worry.
Read on: Connecting a domain to your server (DNS basics) →

Emails sent from the server land in spam or are rejected (the mail log shows e.g. does not resolve to address or no PTR record).

The reverse-DNS entry (PTR) is missing or doesn’t match the sender hostname. Set the PTR as described in step 5 at the VPS provider and make sure it points to the same name that also resolves via the A/AAAA record.
Read on: Connecting a domain to your server (DNS basics) →

did not find expected key (or similar YAML errors).

YAML is indentation-sensitive – spaces only, never tabs, and consistent per level (common: 2 spaces). Check the file without starting it: docker compose config reports the error with line and column (go-yaml load error in parser … at L2.C3-L4.C4 – the broken line is the second position).
Read on: Docker Compose: services, volumes, networks →

address already in use or port is already allocated on up.

The host port (left in 8080:80) is already taken – in the first case by a program on the server, in the second by another container (docker ps shows which). Find the occupant with sudo ss -tlnp | grep 8080 or choose a different host port.
Read on: Docker Compose: services, volumes, networks →

An app can’t find its database (could not translate host name).

The hostname must be the service name (e.g. db), not localhost. Inside a container, localhost is the container itself, not the neighboring service. And: both services must be in the same Compose project (the same file).
Read on: Docker Compose: services, volumes, networks →

Docker Compose: After docker compose down all data is gone.

Either the volume wasn’t declared as a named volume under volumes: (then it was only the ephemeral container storage), or down -v was used. Always run persistent services with a declared named volume.
Read on: Docker Compose: services, volumes, networks →

docker-compose: command not found.

That’s the old Compose v1 (with a hyphen). The current one is docker compose (with a space, plugin). If it’s missing: sudo apt install docker-compose-plugin (see Docker tutorial).
Read on: Docker Compose: services, volumes, networks →

“Create” won’t make a snapshot while a DVD is inserted.

If an .iso image is attached in the virtual drive under “Media → DVD Drive”, the SCP refuses new snapshots. Eject the image there (the ISO row in the server overview has to show - again) and start the snapshot once more.
Read on: netcup SCP: snapshots, console & rescue →

The snapshot can’t be created because there isn’t enough disk space.

A snapshot needs room next to your live data. Clean up on the server, hand the freed blocks back to the host with fstrim -av, and delete snapshots you no longer need. If that doesn’t help, trigger the Storage Optimization in the SCP under “Media → Disks”. Plan for downtime: netcup shuts the server down for it, optimizes the disk and boots it again.
Read on: netcup SCP: snapshots, console & rescue →

After an online snapshot restore, the database is corrupted.

An online snapshot may catch a running write mid-way. For servers with a database, take an offline snapshot or create a database dump beforehand.
Read on: netcup SCP: snapshots, console & rescue →

You can’t get into the SCP.

The SCP uses its own credentials (not SSH). They are in the welcome email; a forgotten SCP password you reset in the netcup customer account (CCP).
Read on: netcup SCP: snapshots, console & rescue →

After ufw enable you can no longer get in via SSH.

The SSH rule was missing or targeted the wrong port. Connect via the console in the netcup SCP (VNC, independent of SSH), allow your SSH port there (sudo ufw allow …) and test again. That’s exactly what step 3 warns about.
Read on: Setting up a firewall with UFW →

ERROR: Could not find a profile matching 'OpenSSH'.

The OpenSSH profile only exists if openssh-server is installed. Use the port number instead: sudo ufw allow 22/tcp (or your port). sudo ufw app list shows the available profiles.
Read on: Setting up a firewall with UFW →

A Docker container is reachable from outside even though UFW doesn’t open the port.

Not your mistake – Docker bypasses UFW. Docker writes its rules directly into iptables and inserts them ahead of the UFW chains. A published container port (ports: in the compose.yaml) is thus open, no matter what UFW says. The clean solution is a second firewall layer in front of the server – at netcup the firewall in the SCP as an upstream perimeter. On the host it also helps to bind container ports only to 127.0.0.1 instead of 0.0.0.0.
Read on: Setting up a firewall with UFW →

After activating, name resolution stops working (apt update hangs, ping domain.de fails, but ping 1.1.1.1 works).

The DNS replies are being blocked. Check the rule in the base template INBOUND UDP ACCEPT, Src port 53 (source port, not destination port).
Read on: Setting up the netcup firewall in the SCP →

The clock drifts, or TLS certificates are rejected due to the wrong time.

The NTP replies are missing. Add INBOUND UDP ACCEPT, Src port 123.
Read on: Setting up the netcup firewall in the SCP →

IPv6 no longer works (v4 does).

The ICMPv6 rule is missing. Without Neighbor Discovery, the server can’t even find its neighbor (router) over IPv6.
Read on: Setting up the netcup firewall in the SCP →

After activating, you can no longer get in via SSH.

The SSH rule is missing or names the wrong port. Via the VNC console (SCP → Display) you can still reach the server; correct the policy and save again.
Read on: Setting up the netcup firewall in the SCP →

The server can’t send emails (outbound port 25 doesn’t work).

Not an error in your policy, but netcup’s default policy “netcup Mail block”. How to take it off is described under unblock port 25.
Read on: Setting up the netcup firewall in the SCP →

The server initially runs normally and is suddenly offline after one or two weeks.

If the server uses DHCP, the lease renewal is blocked by the whitelist. Add INBOUND · UDP · ACCEPT · Src 67 to the base template (see the DHCP tip in step 2).
Read on: Setting up the netcup firewall in the SCP →

E: Package 'docker-ce' has no installation candidate.

The package source from step 2 is missing or malformed – apt only knows the name from the Debian packages' dependencies and finds no package behind it. Check the contents of /etc/apt/sources.list.d/docker.list – it must contain your Debian version (e.g. trixie) – and then run sudo apt update again.
Read on: Installing Docker on Debian →

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock.

The docker group membership hasn’t taken effect yet. End the SSH session and reconnect; groups must then include docker. If not, repeat step 4.
Read on: Installing Docker on Debian →

Conflicts during installation with already-present packages.

Another Docker variant is already installed (docker.io, podman-docker, …). Remove the old packages first: sudo apt remove docker.io docker-doc docker-compose podman-docker containerd runc – existing containers/images are preserved.
Read on: Installing Docker on Debian →

docker compose reports docker: unknown command: docker compose.

The Compose plugin is missing – Docker was probably installed differently earlier. Run sudo apt install docker-compose-plugin. Note: the old docker-compose (with a hyphen) is a different, outdated tool.
Read on: Installing Docker on Debian →

SSH keeps asking for the password despite ssh-copy-id.

Usually the file permissions on the server are wrong: SSH ignores authorized_keys if group or others may write to ~/.ssh. The log on the server (sudo journalctl -u ssh --since -5min) then shows Authentication refused: bad ownership or modes for directory /home/koch/.ssh. Fix it with chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys, and also check that you’re connecting with the right user (koch@…, not root@…).
Read on: Hardening SSH access →

With Permission denied (publickey) you can’t get in at all anymore.

Password login was disabled before the key worked. Open the VNC console in the netcup SCP, log in locally there, temporarily set PasswordAuthentication yes in /etc/ssh/sshd_config.d/00-harden-ssh.conf, restart SSH and start again at step 2.
Read on: Hardening SSH access →

After the restart the SSH service no longer starts.

The configuration has a syntax error; a mistyped PasswordAuthentification is enough (hence sshd -t in step 4). Log in via the VNC console; sudo sshd -t then names file, line and option: /etc/ssh/sshd_config.d/00-harden-ssh.conf: line 2: Bad configuration option: PasswordAuthentification, followed by … terminating, 1 bad configuration options.
Read on: Hardening SSH access →

The settings seem to take effect, but password login still works.

Your file isn’t the first one to set the value (see “The first value wins”). If sshd -T from step 4 shows yes, check with ls /etc/ssh/sshd_config.d/ whether another file sorts before yours and whether yours really ends in .conf. The Include line only picks up those. Then restart SSH.
Read on: Hardening SSH access →

ssh: connect to host … port 22: Connection timed out.

Usually the IP was mistyped or the server isn’t fully provisioned yet. Check the IP in your customer account and whether the server is shown as “online” there. Wait a few minutes after ordering.
Read on: First steps with a netcup VPS →

Permission denied, please try again on root login.

Wrong password, often a copy-paste issue with invisible trailing spaces, or a different keyboard layout. Copy the password without surrounding spaces directly from the credentials.
Read on: First steps with a netcup VPS →

WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!.

The server was reinstalled and has a new host key, and SSH rightly raises the alarm. If you reinstalled it, remove the old entry with ssh-keygen -R YOUR_SERVER_IP and reconnect. If you didn’t reinstall, investigate before you connect.
Read on: First steps with a netcup VPS →

sudo: command not found as the new user.

On minimal images the package is sometimes missing. Install it as root: apt install sudo. Then check that the user is in the group: groups koch must contain sudo, otherwise repeat step 3 and log out and back in once.
Read on: First steps with a netcup VPS →