Troubleshooting - Aion Docs

Missing Optional Dependencies

The extras supply the third-party libraries each part of the SDK runs on. The first call that needs one from an uninstalled extra raises MissingOptionalDependency, with the install command in the message:

LangGraph authoring requires optional dependencies.
Install them with: pip install "aionto-sdk[langgraph-authoring]"

For the server layer, where either framework extra would do, the message names both:

aion serve requires optional dependencies.
Install one of the agent server extras:
  pip install "aionto-sdk[langgraph-server]"  # LangGraph agents
  pip install "aionto-sdk[adk-server]"        # Google ADK agents

MissingOptionalDependency is both an AionError and an ImportError, so except ImportError around an SDK import catches it. A plain ModuleNotFoundError naming an aion.* module is a different failure: the installation itself is incomplete. Recreate the environment and install the SDK again rather than reinstalling over it.

`aion serve` Fails to Start

Confirm an agent server extra is installed — see above.
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. refusing to fall back to an in-memory store in the log means the URL is set but the database is not ready.
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 the proxy is running.
aion chat connects to http://localhost:8000 by default. Pass --host when the proxy started on another port — aion serve prints the address it took.
To reach one specific agent, pass --agent-id with an ID configured in aion.yaml.

Chat Fails to Start

aion chat runs the terminal UI bundled with the Python package, which needs Node.js 22+ on PATH. Without it the command exits before connecting:

Unable to locate the standalone chat artifact.

Install Node.js 22+, or use the standalone npm client — see Aion Chat.

Port Conflicts

Use a custom range:

aion serve --port-range-start 7000 --port-range-end 7100

Or pin the proxy port explicitly:

aion serve --port 9100

Configuration Validation Errors

Ensure root key is aion.
Ensure each agent has required path.
Write input_modes and output_modes as media types (image/png, image/*) or as the short names text, json, image, audio, video.
Keep agent paths unique across entries.

​Missing Optional Dependencies

​aion serve Fails to Start

​Startup Confirmation Timeouts

​Chat Cannot Reach Agent

​Chat Fails to Start

​Port Conflicts

​Configuration Validation Errors