# Troubleshooting

> Debug route attachments, tunnel connectivity, and common failure modes.

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 <name>`, 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:

```bash title="terminal"
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 <name>`.

### 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

```bash title="terminal"
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](/docs/docs/getting-started/kubernetes.md).