Troubleshooting

This guide helps you diagnose common issues with route attachments, tunnel connectivity, and Kubernetes mirroring.

Routes not attaching

When a route doesn't show up in apoxy gateway get, work through this checklist:

1. Confirm the right project — check your Apoxy config has the correct project selected.
2. Confirm the Gateway exists — run apoxy gateway list and verify the Gateway name.
3. Check parentRefs — the route must reference an existing Gateway by the correct name.
4. Check the route type — an HTTPRoute won't attach to a TCP-only listener, and vice versa.
5. Check hostnames — if the Gateway listener restricts hostnames, the route's hostnames must overlap.
6. Check sectionName — if specified, it must match a listener name on the Gateway.

Inspect both sides:

apoxy gateway get default
apoxy gateway routes get http/my-route

Compare the route's parentRefs against the Gateway's listener names and protocols.

Tunnel not connecting

If apoxy tunnel run starts but traffic isn't flowing:

1. Check the TunnelNode exists — run apoxy tunnel list and verify the name matches what your route references.
2. Check the tunnel is running — the tunnel client must be actively connected. Look for connection status in the TUI or logs.
3. Check the local service — verify the service is actually listening on the port you specified. Try curl localhost:<port> from the same machine.
4. Check the route backend — the HTTPRoute's backendRefs must use kind: Backend and reference a Backend that exists.
5. Check the Backend exists — run apoxy backend get <name> and verify its endpoint FQDN matches {tunnelNodeName}.tun.apoxy.net.

Kubernetes mirroring not working

If you're using apoxy k8s install and resources aren't appearing in Apoxy:

1. Check the controller is running — look for the Apoxy controller pod in your cluster.
2. Check the mirror mode — --mirror gateway only mirrors Gateway API resources. Use --mirror all if you need Ingress as well.
3. Check cluster connectivity — the controller needs outbound access to the Apoxy API.
4. Check resource types — the controller mirrors Gateway, HTTPRoute, and related types. Custom resources won't be mirrored automatically.

Common error patterns

"no matching parent"

The route's parentRefs don't match any Gateway. Double-check the Gateway name and that it exists in the same project.

Traffic reaches the Gateway but returns 404

The Gateway is accepting the connection but no route matches the request. Check:

• The route's hostnames match the request's Host header.
• The route's path matchers (if any) match the request path.
• The route is actually attached — verify with apoxy gateway get.

Traffic reaches the tunnel but the backend is unreachable

The tunnel is working but the local service isn't responding. Check:

• The port in the route's backendRefs matches where the service is actually listening.
• The service is bound to an address the tunnel can reach (e.g., 0.0.0.0 or localhost, not just 127.0.0.1 if the tunnel is in a container).

Getting more information

apoxy gateway list           # see all Gateways
apoxy gateway get <name>     # Gateway details with attached routes
apoxy gateway routes list    # see all routes
apoxy tunnel list            # see all TunnelNodes
apoxy tunnel get <name>      # TunnelNode details

If the problem is cluster registration or controller installation, see Kubernetes Install.