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.