---
pattern_id: PAT-002
title: "Traefik `reload` unreliable after conf.d edits — use `restart`"
category: infrastructure
severity: medium
status: active
first_observed: 2026-07
last_updated: 2026-08-30
related_systems: [proxmox-cluster, rke2-kubernetes]
related_solution_docs:
  - docs/solutions/bug-fixes/2026-07-26-paperless-ingressroute-hostname-fix.md
related_skills: []
---

# Traefik `reload` unreliable after conf.d edits — use `restart`

## Symptom

After modifying Traefik configuration files (especially dynamic config in `conf.d/`),
issuing a `reload` signal (SIGHUP) does not reliably pick up the changes. The old
configuration remains active, leading to stale ingress routes, incorrect routing,
or 404 errors.

## Root Cause

Traefik's hot-reload mechanism for file-based dynamic configuration can silently fail to
detect changes, especially when:
- Files are edited in-place (atomic rename not used)
- The file watcher misses events on certain filesystems (e.g., overlayfs, NFS)
- rsync is used without `--inplace` (creates temp file + rename, which the watcher may miss)

## Mitigation

Use `restart` instead of `reload` for Traefik container/service after conf.d edits:
```bash
# Instead of: docker kill -s HUP traefik  (or systemctl reload traefik)
# Use:
docker compose restart traefik
# or: systemctl restart traefik
```

Additionally, when syncing config files via rsync, use `--inplace` to avoid
temp-file-rename patterns that confuse file watchers:
```bash
rsync --inplace -av ./conf.d/ /etc/traefik/conf.d/
```

## Prevention

- Always use `restart` (not `reload`) after Traefik config changes in the Traefik CT (99999)
- Use `rsync --inplace` when pushing config files to the Traefik host
- Document this in deployment runbooks

## Evidence

- Observed during Paperless v3 IngressRoute hostname fix (Jul 2026)
- Traefik runs in CT99999, conf.d directory
- MEMORY.md entry: "Traefik CT99999: `reload` unreliable after conf.d edits. Use `restart` or `rsync --inplace`."