Reading Ferrum Diagnostics
Anvil explains what happened to a request from evidence it actually observed. This guide covers the outcome model, how to read a finding, and exactly how far Ferrum Edge markers can be trusted.
SHA256SUMS. macOS installers are not Developer ID signed or notarized and Windows installers have no code-signing certificate. In-app updates use verified minisign signatures; this does not code-sign the installers. See the preview downloads and Anvil overview.Four Results, Not One
Every execution keeps separate dimensions, so a 200 with a truncated body or a gRPC error inside HTTP 200 is not mistaken for success.
| Dimension | Values | Question it answers |
|---|---|---|
| Transport | completed, failed, incomplete, canceled, unknown | Did the exchange finish on the wire? |
| Application | success, failure, not evaluated | Did the protocol report success: HTTP status, gRPC status, SOAP fault, GraphQL errors? |
| Assertions | pass, fail, not run | Did your own checks pass? |
| Dispatch | not dispatched, sent, may have been sent, unknown | Could the peer have acted on the request? Derived from bytes written and protocol signals, never from error text. |
Anatomy of a Finding
Findings come from deterministic rules over typed evidence, and their wording comes from a fixed catalog. Server-authored text is never used as an instruction.
- Confidence: confirmed, likely, unknown or conflicting
- Scope: the leg the claim is about, such as your connection to the destination, gateway admission, or gateway to backend
- Owner: who can act: you, the network, a proxy operator, the gateway operator or the backend owner
- Evidence: the observed facts and where they came from
- Does not prove, alternatives, remediation and confirm with
| Confidence | Meaning |
|---|---|
| Confirmed | Directly observed. |
| Likely | Strong but indirect, or based on evidence another party could forge. |
| Unknown | The evidence cannot separate the listed causes. |
| Conflicting | The evidence disagrees with itself. |
Findings are ordered by severity, then specificity (hop-specific findings before generic status explanations), then confidence. Order is presentation only; read each card's own confidence. No finding guarantees a root cause.
Declare the Gateway First
Ferrum-specific findings appear only for destinations you declare in a Ferrum gateway integration profile.
- Without a profile, a Ferrum-looking header is reported as an unverified marker (
ferrum.marker.unverified), because any server can send it. - Each profile names its Ferrum Edge release, and Anvil matches responses only against that release's catalog, built from a source audit. Three catalogs ship in v0.1.1: Ferrum Edge 0.9.8, the default for new profiles (540 outcomes and 15 headers), 0.9.7 (538 outcomes and 15 headers), and 0.9.5 (528 outcomes and 14 headers). 0.9.7 and 0.9.5 have seven public
X-Gateway-Errortokens; 0.9.8 addsrequest_timeout. - A profile that names a release without a catalog never borrows another release's catalog. Anvil reports
ferrum.catalog.unavailable(confidence unknown), matches no outcomes, and reads a token only with the coarse meaning every audited release shares. Such releases have not been validated. - Marker-based claims are capped at likely, even for a declared gateway over verified TLS: on 0.9.7 and 0.9.5 a backend can inject
X-Gateway-ErrorandX-Gateway-Upstream-Statuson some paths, such as native gRPC responses and plugin reject maps. 0.9.8 strips backend marker copies, but an intervening proxy can still inject them. The same cap applies to a release without a catalog. - A declared gateway used over plain HTTP, for example in a local lab, is also capped at likely.
- Edge v0.9.9+ provides opt-in diagnostic references, but Anvil v0.1.1 has no catalog or authenticated resolver for those releases. Its gateway attribution remains capped at likely.
What Markers Can and Cannot Prove
The tokens are coarse: 0.9.7 and 0.9.5 have seven, and 0.9.8 adds request_timeout. Anvil does not infer a precise cause from them.
| Token | What Anvil says | Never claimed from the token alone |
|---|---|---|
connection_failure | The gateway could not set up a connection to the configured backend (DNS, TCP, TLS, pool and similar). | That TLS failed, that DNS failed, or that your client certificate is wrong. |
backend_timeout | The gateway's backend deadline elapsed. Other 504 responses can carry a different token, including request_timeout in 0.9.8. | That the backend received the request, or that it is slow rather than unreachable. |
request_timeout (0.9.8) | The route deadline expired before a backend held the current attempt. | That no earlier retry reached a backend, or which phase used the budget. |
backend_error | The backend path failed or the gateway refused locally. | That the backend returned this error. |
circuit_breaker_open | The gateway's breaker for this backend is open. | That the backend is down right now. |
overload | The gateway shed load, was draining, or hit its response-transform ceiling. | CPU pressure. |
config_stale | The data plane's configuration fence is stale. | Which configuration change is missing. |
concurrency_limit | A concurrency limit rejected the request. | The limit value or the cause of the load. |
Absence is not evidence
A missing marker does not prove a response came from the backend. Gateway authentication rejections carry no X-Gateway-Error; their bodies can be reproduced by a backend, so they stay at likely at most.
A 403 is not a WAF verdict
The WAF and bot-detection default bodies are byte-identical, and backend 403s look the same, so a 403 alone never proves a WAF block.
connection_failure token through a local Ferrum Edge 0.9.7 gateway, reported as Likely with its limits spelled out.Safety Rules in Every Remediation
- Disabling TLS verification or the WAF is never suggested as a default fix.
- A request whose dispatch is may have been sent is never suggested for retry when its method is not idempotent, and the engine does not replay it automatically.
- Remediation names an owner: gateway-to-backend problems go to the gateway operator or backend owner, not to your credentials.
- Use Copy redacted support bundle to share a result; secrets are redacted by name and by exact value.
How this is checked
A failure lab drives the real, checksum-pinned Ferrum Edge 0.9.8 release binary (the default) on loopback, with 0.9.7 and 0.9.5 also supported; the trusted gateway profile names the release under test. Every scenario runs with and without a trusted gateway profile, lookalike backend responses must not be blamed on the gateway, and gateway logs serve only as ground truth for the checks. Skipped scenarios are never counted as passes.