Self-Hosted App Session Troubleshooting Guide for Proxy and Cookie Changes
The safe approach is to treat a layer-by-layer comparison of direct and proxied requests, response cookies, browser storage, and backend session state as a sequence of observable gates, not a single command.
On a self-hosted web application behind a reverse proxy, the practical risk is users are logged out, trapped in a redirect loop, or unable to establish a session after proxy or cookie changes. Record the current identity and recovery point, start with the least invasive discriminator, interpret pass and fail results before changing another variable, and stop when storage becomes unstable or the only recoverable copy would be exposed. The workflow below ends only after the original workload succeeds or the evidence reaches an escalation boundary.
Reproduce one session path and preserve evidence
Choose one user, browser profile, hostname, and login path. Record the first failing request, status sequence, redirect locations, response Set-Cookie headers with values redacted, request cookies, proxy logs, app logs, and the exact configuration change that preceded the failure.
Do not begin by clearing every cookie or rotating the application secret. Use a private browser profile as a clean control while preserving the failing profile for comparison. Confirm whether direct backend access works; that separates application authentication from proxy-derived URL and cookie behavior.
Stop if the application exposes tokens in logs, the proxy accepts spoofed forwarding headers from untrusted clients, or login bypasses TLS. Protect credentials and correct the security boundary before continuing functional troubleshooting.
Verify scheme, host, and forwarding trust
Compare the external URL with what the application believes: scheme, host, port, base path, and client IP. Inspect Host, X-Forwarded-Proto or standardized forwarding headers, and the application’s trusted-proxy list. A backend that believes HTTPS requests are HTTP may refuse Secure cookies or generate an endless redirect to HTTPS.
Use one trusted proxy to set or replace forwarding headers and configure the application to trust only that hop. Do not append client-supplied values blindly. Test a login and one absolute redirect after each change rather than altering proxy headers and application base URL together.
The ZimaSpace guide on direct-versus-proxied login diagnosis uses the same direct-versus-proxied comparison after a proxy restart. Its Immich example is narrower, but the evidence path transfers: prove the backend session works, then inspect forwarding headers, routing, and browser state.
Inspect cookie scope and browser decisions
Check cookie name, Domain, Path, Secure, HttpOnly, SameSite, expiration, and whether duplicate cookies with the same name exist at different paths or domains. Browser developer tools show whether a cookie was stored, rejected, or omitted from the next request; server logs alone cannot reveal that decision.
OWASP’s SameSite cookie behavior explains how SameSite values control cross-site cookie delivery. If authentication crosses sites or uses an embedded flow, SameSite=None also requires Secure; for a simple same-site application, broadening the cookie unnecessarily weakens the design.
Delete only the affected cookie in the control profile after recording it, then repeat the login. If a fresh cookie works while the preserved profile fails, compare scope and expiry; if both fail, return to response headers or backend session storage rather than repeatedly clearing state.
Check shared session state and validate the fix
For multi-container or replicated applications, confirm every instance uses the same session-signing secret, time source, and shared session backend when required. A proxy that alternates between instances can look like random logout when one instance cannot validate another’s cookie.
PortSwigger’s discussion of SameSite security boundary is security-focused, but it clarifies that SameSite is a browser boundary rather than a generic login repair switch. Preserve CSRF protection while matching the application’s actual origin and redirect flow.
Validate login, logout, idle expiry, browser restart, password change, and access through the intended internal and remote hostnames. Close the issue only when old cookies fail safely, new sessions survive normal routing, and no forwarding or cookie attribute was loosened beyond the documented need.
Recommended products
Support & Tips
More to Read
NFS Migration Checklist for Renamed Datasets and Stable File Handles
Assume file handles may change when storage identity changes. Quiesce clients, cut over the export deliberately, remount, and verify open and new files.
SMB Client Troubleshooting Guide for Windows, macOS, and Linux
Use the same server, account, share, and file operation on each client so discovery, credentials, policy, and storage faults do not get mixed together.
Home Server Secret Rotation Checklist for Apps, Databases, and Backups
Treat rotation as a dependency migration: map every consumer, overlap credentials where possible, verify the new value, then revoke and test recovery.
