Troubleshooting guide
Browser or curl works. Your app still fails.
An AI agent connection error is only a symptom. A successful curl run from another shell does not attest to the Agent subprocess, container, sandbox, DNS view, or proxy route. Start by measuring the path where the failure actually occurs.
In short: A curl success in another shell says nothing about the Agent's subprocess, container, DNS view, or proxy route. Run the check from the failing runtime and compare its Evidence with the working one.
Last updated
Terms on this page: Control is NetOkay's public service at netokay.net. Every check reaches it first, so a failing target can be compared with a path that is known to work. Evidence is the single JSON EvidenceBundle that a CLI or Agent run writes to stdout: observed facts, explicit unknowns, policy decisions, and redaction notes.
1. Check the browser’s connection
Check your public IP, then run the WebSocket test or streaming test if that matches the symptom. These fixed tests reach NetOkay; a pass leaves your original application and destination untested. A short stream does not prove long-term stability, and events arriving together do not identify a proxy as the cause.
2. Compare browser and terminal
Open Compare environments. Run the supplied self API command in the terminal, container, or IDE you want to compare, then paste its response. The page compares public IP and address family; country, ASN, and time are context. Identical IPs do not prove identical paths. Different IPv4/IPv6 families do not prove a proxy is wrong.
3. Check the original application’s environment
If the app still fails, inspect its own proxy settings, inherited environment variables,
certificate store, timeout, and service authentication. Retry the original failing operation
to verify any fix. A successful terminal check alone cannot verify an Agent’s internal
request. If the app runs on Node and reports TypeError: fetch failed,
read the error’s cause code to see which of these
settings to check.
Why curl success is not an Agent result
Two commands on the same machine can inherit different environment variables, certificate stores, proxy rules, DNS resolvers, timeouts, or container boundaries. Browser success is a third observation again. It proves that the browser reached its destination, not that the Agent can reach the same target.
NetOkay runs a bounded, read-only check from the invoking CLI subprocess. It compares one approved public HTTP or HTTPS target with NetOkay's fixed Control path and returns one JSON EvidenceBundle. The result records facts, limitations, and unknown fields instead of turning missing data into success.
Run the check where the failure lives
- Open the NetOkay get-started workflow from the same terminal, IDE, container, sandbox, or Agent host that reports the error.
- In Agent mode, install the Skill from its stable source and let it verify the ready release manifest before invocation. Do not substitute an unverified artifact.
- Run one explicit public target from the failing runtime and preserve the exit status.
- Read the Control and target observations together, including unknown fields and route limitations.
Interpret the evidence without overclaiming
- Control succeeds and the target fails: the observed difference is target-path specific. Review the recorded DNS, TLS, HTTP, and route facts before changing configuration.
- Control and target both fail: the invoking runtime could not complete either bounded path. The evidence may narrow the boundary, but it does not identify one cause by itself.
- The target succeeds from the Agent runtime: the reported error may sit outside the measured network boundary, such as authentication, application state, or an Agent service session.
- A route or target is blocked: keep the safety boundary intact. Confirm the public target and supported route instead of disabling validation or widening access.
What the EvidenceBundle does not prove
NetOkay does not inspect the Agent's internal runtime, retain credentials or response bodies, scan private networks, or claim that one service vantage point represents a region. Proxy secrets stay out of the output, and an unobservable destination address remains explicit rather than being replaced with the proxy address. The result narrows the boundary; it does not prove a unique root cause.
Test the original target from the failing environment
A matching public IP leaves DNS, certificates, application proxy handling, and authentication unverified. Different addresses or families tell you what to compare next, without identifying a unique cause.
Check website status, or run a check from your terminal, then read the target observations and limitations. This HTTP/HTTPS step does not automatically test your application’s streaming protocol or internal client.
Change one setting and repeat the same check. For protocol-specific symptoms, use the WebSocket guide or SSE guide.