Troubleshoot edge and origin

Preserve identity and active runtime state

Do not delete agent state, reset revision numbers, or edit generated gateway or cell files. Those actions can destroy the evidence and last-valid state needed for safe recovery.

For gateway listener, Host/SNI rejection, revision drift, and last-valid recovery, see Edge gateway ingress.

Agent will not enroll

• Confirm EDGE_ID and the one-time token belong to the same enabled edge.
• Verify server trust through EDGE_CONTROL_CA_CERTIFICATE.
• Check edge-control port 8443, hostname SAN, firewall, and clock.
• Preserve the pending agent state so an exact CSR retry can succeed.
• If the token was consumed with another CSR or identity state was lost, rotate identity and use a new token.

Heartbeat is stale

Check the agent container, client certificate expiry/serial, edge-control availability, queue/network reachability, and persistent state permissions. Do not make the edge routable by editing its timestamp.

The administrator edge status and Cells/Endpoints tables refresh every five seconds. A healthy agent normally updates its heartbeat on that cadence. If the timestamp remains fixed, inspect the agent log for the stable HTTP error. In particular, active_sequence was not issued to this edge means the agent's local active state is ahead of both the edge's durable acknowledged sequence and retained artifacts; do not reset the sequence or delete agent state. Restore the matching control-plane database or intentionally reconcile/replace the edge identity and state as one recovery operation.

heartbeat_stale is the primary loss-of-contact reason. gateway_not_ready is evaluated only after heartbeat freshness and means the fresh snapshot did not contain a ready gateway/listener. Fix the first reason shown rather than restarting unrelated containers.

Artifact is rejected

Inspect the agent's bounded rejection reason:

• signature/checksum: verify the shared artifact signing key and transfer;
• expired delivery or sequence replay: check edge/control clocks and current artifact sequence; never reset the edge sequence to make an old download fit;
• incompatible artifact: compare agent and compatibility versions;
• candidate validation: inspect domain/pool runtime data and cell name;
• activation failure: check runtime directory ownership and filesystem capacity.

The old active directory should still serve. Fix desired state or agent/runtime capacity, then reconcile.

Listener is not ready

The shared cell must report ready, not drained, and the edge heartbeat must set listener_ready=true. Check /healthz, token-protected status, runtime JSON, bootstrap certificate files, MMDB, cache/temp permissions, and cell resource limits.

Origin test fails

Use the stable result to distinguish DNS, unsafe destination, connect timeout, TLS validation, HTTP status, or response timeout. Recheck SNI and Host separately. Origin addresses are validated again after resolution; a DNS change to a blocked address is intentionally rejected. The numeric peer is checked again in the balancer immediately before each TCP attempt, including retries. Client and cache-key counters occupy separate fixed-size shared zones; a full cache-admission zone skips new stores, while per-domain rate and origin concurrency counters fail closed for that domain.

Follow Edge or cell failure before draining or restarting.