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

# Troubleshooting

> Common issues when running the Aion Python SDK.

## `aion serve` Fails to Start

* Confirm `aion.yaml` exists and contains at least one agent.
* Verify `path` targets are importable.
* If you expect control plane connectivity, ensure control plane environment
  variables are set.
* If you expect durable persistence, ensure `POSTGRES_URL` is configured and the
  database is reachable.
* Check whether requested ports are already occupied.

## Startup Confirmation Timeouts

Increase startup timeout for slower systems:

```bash theme={null}
aion serve --startup-timeout 60
```

Skip confirmation only when you understand the tradeoff:

```bash theme={null}
aion serve --startup-timeout 0
```

## Chat Cannot Reach Agent

* Confirm proxy is running.
* Confirm `--host` matches proxy URL.
* When using proxy, pass `--agent-id` with a valid configured ID.

## Port Conflicts

Use a custom range:

```bash theme={null}
aion serve --port-range-start 7000 --port-range-end 7100
```

Or pin proxy port explicitly:

```bash theme={null}
aion serve --port 10000
```

## Configuration Validation Errors

* Ensure root key is `aion`.
* Ensure each agent has required `path`.
* Use valid mode values in `input_modes` and `output_modes`.
* Keep agent paths unique across entries.