Troubleshooting & FAQ

Troubleshooting

CLI and desktop disagree

They share one uplink-core state, so a mismatch usually means a stale agent. Inspect it without starting it:

uplink agent status

Check the state directory, socket path, log path, sidecar path, protocol version, and live snapshot.

Empty reply on a local dev server

Some dev servers (e.g. Astro) bind only IPv6 loopback by default while the connector dials IPv4 loopback. Bind your upstream explicitly to 127.0.0.1.

A self-hosted edge misbehaves

From the self-host deployment directory, inspect Compose and run the built-in diagnostics:

docker compose ps
docker compose logs --tail=100 uplink-edge caddy certificate-renewal
docker compose run --rm operator doctor --domain <edge-host>
docker compose run --rm operator --output=json doctor --domain <edge-host>

doctor validates DNS, TLS, configured providers, and the edge health endpoint. The published operator service also reads the host’s memory and UDP-buffer values through three narrow, read-only procfs mounts. It cannot inspect host or cloud firewall rules from inside a container, so its firewall warning is a prompt to verify 80/tcp, 443/tcp, 443/udp, and 4100/udp manually. Supply the edge server’s public IP to make the DNS comparison explicit, or disable local public-IP detection:

docker compose run --rm operator doctor \
  --domain <edge-host> --no-public-ip-detect
docker compose run --rm operator doctor \
  --domain <edge-host> --public-ip <edge-server-ip>

For a custom-domain failure, leave alias DNS unchanged and confirm that the edge loaded configuration/aliases.yaml before changing records.

A private route denies everyone on a self-hosted edge

Account-based access (owning-account membership and share) needs an identity provider with visitor SSO. Key-only self-hosted edges support public and bearer access, allowed IPs, base request limits, and firewall rules, but not account identity. Use a bearer token there instead.

Bot protection is rejected on an edge

The edge must have a configured challenge provider before it can enforce a service-level managed_challenge or firewall challenge action. Configure both UPLINK_CHALLENGE_PROVIDER_URL and UPLINK_CHALLENGE_PROVIDER_TOKEN on the edge, then record that provider with uplink edge add --challenge-provider or refresh an existing entry with uplink edge refresh. Otherwise turn bot protection off or choose a provider-capable edge. Other firewall actions remain available.

A bearer-token route keeps prompting

Bearer-token browser unlocks use the up_bearer grant, which is separate from account session cookies. Re-entering the token issues a fresh grant.

A response dies mid-transfer with “transfer closed with outstanding read data”

The edge forwards Transfer-Encoding: chunked bodies but deliberately rejects two optional parts of the chunked grammar: chunk extensions and HTTP trailers. Forwarding framing the edge doesn’t itself validate is a request-smuggling primitive, and trailers would bypass the header sanitizing every response goes through, so an origin response that uses either is cut off at the offending byte. Plain chunked responses (no extensions, terminated with a bare 0\r\n\r\n) pass through unchanged. This means protocols that depend on trailers — notably gRPC over HTTP/1.1 — can’t be served through a tunnel; gRPC-Web, WebSockets, SSE, and ordinary HTTP APIs are unaffected.

FAQ

Is the control plane on the request path? No. Visitors hit the edge, and the edge forwards over the connector tunnel to your app. The control plane issues identity and managed capabilities, distributes managed policy, and receives metadata, but it never proxies visitor traffic.

Can I self-host without logging in? Yes. The guided Compose setup mints an edge API key; add the edge on each connector machine with that key. No Uplink account is required. See Self-Hosting.

Can I use my own domain? Yes. On a managed edge, add and verify it in the dashboard, then assign it with the publish picker or custom_domain in uplink.yaml. On a standalone key-mode edge, the operator maps it to the generated host in the edge’s YAML alias policy and owns its DNS. See Custom Domains.

What’s private by default? uplink serve <port> and any service without public: true are private and identity-gated at the edge. Every verified member of the owning personal or organization account gets access, plus any invited emails or valid bearer-token holders. Account identity needs a managed edge; a standalone edge requires an explicit bearer token or public access and rejects an unsupported identity-only route before publishing.

Do edge metrics include request bodies? No. Edge metering is metadata-only; headers and bodies never leave the request path.