Node HandbookNODE HANDBOOK中文
CLI · network

Codex CLI cannot reach the network: check the stage, not the prompt

A terminal tool has no browser to fall back on. When it fails, the error text usually names the layer — resolution, connection, TLS, proxy or authentication — and that is the only thing worth acting on first.

Node Handbook editorial team ·

Save evidence by stage

StageTypical evidenceWhat it rules in
Name resolutionA host-not-found style error naming the endpointDNS configuration, resolver reachability, split-horizon DNS
TCP connectConnection refused or timed out, with the host and portFirewall, egress policy, wrong port, blocked route
TLSCertificate verify failed, unknown authority, handshake failureInspection proxy, missing root certificate, clock skew
ProxyProxy connection failed, or a CONNECT rejectionProxy environment variables, credentials, allowlist
HTTP status401, 403, 429, 5xx with a response bodyAuthentication, 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

  1. 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.
  2. Test resolution separately. A host lookup for the endpoint host, using the same resolver the shell uses. If that fails, nothing downstream can work.
  3. 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.
  4. 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.
  5. Check proxy variables. Print HTTPS_PROXY, HTTP_PROXY and NO_PROXY in the same shell that runs the tool. Note that sudo and background services often do not inherit them.
  6. 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 443 to 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.