Skip to main content

​
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:
Skip confirmation only when you understand the tradeoff:

​
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:
Or pin proxy port explicitly:

​
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.