Save evidence by stage
| Stage | Typical evidence | What it rules in |
|---|---|---|
| Name resolution | A host-not-found style error naming the endpoint | DNS configuration, resolver reachability, split-horizon DNS |
| TCP connect | Connection refused or timed out, with the host and port | Firewall, egress policy, wrong port, blocked route |
| TLS | Certificate verify failed, unknown authority, handshake failure | Inspection proxy, missing root certificate, clock skew |
| Proxy | Proxy connection failed, or a CONNECT rejection | Proxy environment variables, credentials, allowlist |
| HTTP status | 401, 403, 429, 5xx with a response body | Authentication, quota, rate limits, service incident |
“Fetch failed” and similar wrappers are containers, not diagnoses. The nested error names the stage. Record both, plus the exact time.
Check order
- Confirm the endpoint is right. A base URL from a different environment, an internal mirror, or a trailing path is a common cause of a 404 or a TLS mismatch that looks like a network fault.
- Test resolution separately. A host lookup for the endpoint host, using the same resolver the shell uses. If that fails, nothing downstream can work.
- Test the port. A TCP connection attempt to the host and port the tool uses. Refused and timed out point at different things: refused is usually a listener or policy decision, timed out usually routing or filtering.
- Test TLS. An HTTPS request to the same host from the shell. A certificate error here, in a corporate network, usually means TLS inspection whose root certificate is not installed for this tool's trust store.
- Check proxy variables. Print
HTTPS_PROXY,HTTP_PROXYandNO_PROXYin the same shell that runs the tool. Note thatsudoand background services often do not inherit them. - Then authentication. Only once transport works does a 401 or 403 mean anything about credentials or quota.
Why the browser working proves nothing
Browsers read system proxy settings and trust the operating system's certificate store. Command-line tools frequently do neither: they read environment variables and use their own bundled certificate bundle. A machine can have a perfectly working browser and a CLI that cannot resolve, cannot connect, or cannot verify.
That asymmetry is the reason to test each layer from the shell rather than from the browser.
Corporate networks
- TLS inspection: install the organisation's root certificate through its documented procedure, and make sure the tool's trust configuration actually loads it. Do not disable verification — that converts an expected control into an undetected risk.
- Egress allowlists: confirm the endpoint host and port are permitted. A proxy that allows
443to some hosts and not others produces failures that look random until you check the list. - Proxy authentication: some proxies require credentials in the URL or a separate configuration. Confirm with the network team rather than guessing a format.
- Managed devices: policy may forbid changing trust or proxy settings. In that case the answer comes from the administrator, not from a workaround.
What not to do
- Do not put a token or key on the command line where it lands in shell history and process listings.
- Do not disable certificate verification to “get unblocked”.
- Do not loop the same failing command; it produces no new information.
- Do not paste full error output into a public issue without checking for hostnames, internal paths and identifiers.
What to record
- Tool version, OS, and whether the device is managed.
- Time, the exact first error and the nested error, plus the exit code.
- The endpoint host and port, with any private hostname masked.
- Whether resolution, TCP and TLS each succeed from the same shell.
- Proxy environment variables as configured, with credentials removed.
- Whether the same command works on another network.
Scope
This page describes a staging method for a command-line tool that cannot reach its endpoint. It is not specific to one release, and it contains no reproduction on a particular corporate network. Error wording differs between tools and versions, so the stage matters more than the sentence.