Troubleshooting

Service won't start

• Missing SESSION_SECRET — required env var. Generate with openssl rand -hex 32.
• Permission denied on data dir — the service user (speedyfiles or container UID 8443) needs write access to /data and /srv/files.
• Port 5300 already in use — ss -ltnp | grep 5300 to find the squatter.

# Check logs:
docker logs speedyfiles                     # Docker
journalctl -u speedyfiles -n 100 --no-pager # systemd

Email isn't being sent

1. Admin → Settings → Mail → Send test. Watch for green/red banner.
2. Red? Read the error: SMTP timeout (firewall), auth failed (wrong creds), TLS failed (port/encryption mismatch).
3. Common gotchas:
   • Gmail: needs an App Password, not your real password
   • Port 25 outbound is often blocked by residential ISPs — use 587 + STARTTLS
   • SES requires the From-address domain to be verified

Magic links arrive in spam

See Deliverability. Top causes:

• No PTR / rDNS on your sending IP
• Missing SPF / DKIM / DMARC on your sending domain
• Brand-new domain (no sending reputation yet)
• Spam-classifier triggers in your content (test with mail-tester.com)

Magic link returns 410 unexpectedly

• Token expired (TTL elapsed since creation) — create a new package or extend expiry
• Package revoked — check audit log for an admin_revoke event
• Token doesn't exist — typo in the URL, or the database was reset

The audit log on the package detail page will tell you exactly which.

Upload fails partway through

• nginx client_max_body_size not set to 0 — see the install guide
• nginx proxy_read_timeout too low for big files — set to 7200s
• Cloudflare in front? Free plan has a 100 MB upload limit
• Disk full on the storage volume — df -h /srv/files

504 Gateway Timeout on uploads

Almost always a reverse-proxy timeout. Adjust:

# nginx
proxy_read_timeout 7200s;
proxy_send_timeout 7200s;
send_timeout 7200s;

# Caddy
reverse_proxy localhost:5300 {
  flush_interval -1
  transport http {
    response_header_timeout 7200s
  }
}

"DNS filter blocked files.<mydomain>"

Some DNS filtering services (Cloudflare Gateway with the "file sharing" category enabled, NextDNS, etc.) treat files. subdomains as risky. If your LAN's DHCP hands out a filtering resolver, your devices may NXDOMAIN their way to confusion. Whitelist the domain in your DNS filter or use Cloudflare 1.1.1.1 / Google 8.8.8.8 at your WAN.

"I lost the admin password"

# From the host (Docker):
docker exec -it speedyfiles python -m app.cli reset-password \
  --email admin@example.com --new-password 'new-strong-password'

# From the host (bare-metal):
sudo -u speedyfiles /opt/speedyfiles/.venv/bin/python -m app.cli \
  reset-password --email admin@example.com --new-password 'new-strong-password'

"Forgot my SMTP password I just typed in"

It's Fernet-encrypted in the DB — not recoverable. Re-enter it under Settings → Mail.

Rotating SESSION_SECRET

Rotating invalidates:

• All active sessions (everyone gets logged out)
• All stored encrypted secrets (SMTP passwords primarily — they'll appear blank in the UI and need to be re-entered)

Magic-link tokens, API tokens, and password hashes are unaffected (they don't use SESSION_SECRET for encryption).

Where to ask

• GitHub Issues — bug reports + feature requests
• GitHub Discussions — usage questions, ideas