> ## Documentation Index
> Fetch the complete documentation index at: https://fracta.quasarops.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues across all deployment modes

## By deployment mode

### Local process

### Docker Compose

### Kubernetes

The most complete troubleshooting reference for kubernetes mode lives in the [Kubernetes Runbook](/guides/deployment/kubernetes-runbook). The table below summarises the most common issues.

| Symptom                      | Likely cause                          | Fix                                        |
| ---------------------------- | ------------------------------------- | ------------------------------------------ |
| Pod stuck in `Pending`       | PVC not bound, node selector mismatch | Check PVC binding and node labels          |
| Agent Job exits immediately  | Image pull failure or missing config  | `kubectl describe job/fracta-agent-<task>` |
| Tool calls return 401        | Credential profile not mounted in pod | Check ConfigMap/Secret references          |
| Gateway can't reach FalkorDB | Service DNS or port mismatch          | Verify `falkordb.fracta.svc:6379`          |

## By symptom

### Agent stays in `queued` forever

### Agent fails with "no runtime configured"

### Gateway tool calls return `unauthorized`

### `fracta init` fails

## FAQ

### Can I run multiple control planes on one machine?

### How do I move agents between deployment modes?

### What happens to a worktree if I git push from outside fracta?