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: 
aion serve --startup-timeout 60
Skip confirmation only when you understand the tradeoff: 
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: 
aion serve --port-range-start 7000 --port-range-end 7100
Or pin proxy port explicitly: 
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.