Troubleshoot a service
Select the affected route and reproduce one request before changing configuration.
Symptom: the management UI reports System unreachable
The UI opens System unreachable when a management API request cannot connect, times out, or returns an unavailable gateway response. It checks reachability automatically; use Retry to check sooner.
Check the Core and Edge containers, their logs, and the network path to the management hostname. After the API responds again, the UI returns to the previous page.
Symptom: the route is missing
Checks
- For a UI-owned route, open Proxy routes and confirm it was saved.
- For a label-owned route, open Services → ContainerProxy, confirm discovery is reconciling normally, and select the container's status icon.
- Fix every unrecognized label, warning, validation failure, or ownership conflict shown in the status dialog, then check Logs for the matching reconciliation event.
Resolution
Fix the route in its owning source. Do not create a second UI route for a label-owned service.
Verify
Confirm one route exists for the hostname and it names the expected cluster.
Symptom: the route returns an upstream error
Checks
- Open Upstream destinations and Upstream clusters for the selected route.
- Confirm the destination address, scheme, port, health, and cluster membership.
- Filter Logs by route and status to separate connection failures, timeouts, and upstream responses.
Resolution
Correct the destination or restore upstream reachability. Keep proxy error handling enabled while diagnosing so clients receive a bounded response.
Verify
Send a normal request and confirm the expected upstream response appears in Logs.
Symptom: HTTPS is unavailable or does not redirect
Checks
- Open Certificates and confirm an Active certificate covers the exact hostname.
- Confirm the hostname resolves to Clearplane.
- Check Edge application logs for
TLS handshake failed. For TCP HTTPS, this warning records the exception, connection ID, remote endpoint, and SNI server name, including certificate-selection failures before an HTTP request exists. Successful handshakes do not emit this warning. HTTP/3 uses QUIC and is outside this TCP handshake diagnostic. - For HTTP validation, confirm upstream systems do not cache, redirect, or rewrite the validation path.
- Confirm the route enables the HTTP-to-HTTPS redirect.
Resolution
Restore validation reachability or use DNS validation, wait for the certificate to become Active, then enable the redirect.
Verify
Confirm the browser trusts the HTTPS URL, then confirm the HTTP URL redirects to it.
Symptom: an expected request is blocked
Checks
- Look up the client address in IP control → Address lookup. It shows active bans, IP filter matches, allowlist entries and the recent blocked requests by reason.
- Filter Logs by route, client address, Blocked by and status.
- Use Analytics to identify the block source.
- Open IP control → Blocked IPs to inspect the active ban, source policy, reason, and expiry. Turn on Include lifted and expired to see earlier bans.
- Inspect the route's policy states and its auto-ban, access control, authentication and rate limit policies.
Resolution
Make the narrowest change in the owning policy. For an automatic ban, correct the counted status codes, threshold, window, duration, or route scope before lifting the active ban. Shared public addresses may require a higher threshold or a narrower policy.
Verify
Repeat one expected request and one request that should still be blocked. Confirm both outcomes in Logs.
Symptom: large uploads return 413
Checks
- Compare the upload size with the route's Maximum request body size (bytes), or with the global Maximum request body size (bytes) under System → Settings → Edge → Request safety when the route leaves it empty.
- Inspect the route's WAF policy: in Prevention, Bodies above the limit set to Block rejects bodies above the policy's inspection limit.
Resolution
Raise the limit on the affected route only, in the route form or with clearplane.proxy.maximum-request-body-size-bytes, leaving the global limit unchanged for other routes. For a WAF rejection, set Bodies above the limit to Inspect prefix on that route's policy.
Verify
Repeat the upload and confirm a successful status for the route in Logs.