torana

Troubleshooting

What the common failure modes mean, and what to check first.

torana exits immediately at startup

Startup is fail-fast by design. The error on stderr says which check failed: an unparseable config, a listener address already in use, missing TLS material, or a rejected field (for example an https:// upstream). Fix the config; torana never runs half-configured.

Clients get 502

502 Bad Gateway means the upstream connection failed: the upstream is down, refused the connection, or reset mid-request. Check upstream_connection_errors in metrics and the error log line naming the upstream.

Clients get 504

504 Gateway Timeout means the upstream accepted the connection but didn't return response headers within route.timeout.total (default 30s). Raise the timeout for slow endpoints or fix the upstream.

My reload didn't apply

If the new config fails validation, torana keeps the old one running and logs the reason at error level. Check the logs; fix; SIGHUP again. Also note listener changes need a restart (see Signals).

A config field seems ignored

It probably is, deliberately. Fields for unimplemented features log a startup warning like 'when' expressions are not implemented yet. The configuration table is the source of truth for what's enforced.

Still stuck? Open an issue.