Start
The server refuses a setting and says which.
A refusal is one line on standard error, ERROR <code>: <message>, and the server exits.
The startup messages and error lines below were captured with MCP AIC 0.2.0 and vary by version.
| You see | Cause | Fix |
|---|---|---|
MCP_AIC_WORKSPACE_ROOTS: is required | No folder is allowed | Set it to colon-separated absolute folders |
every entry must be an absolute path | A root is relative | Use absolute paths |
MCP_STUB_SERVER: must be an absolute socket path ... | The registry address is relative | Give an absolute path or a URL |
data directory unavailable: overlaps an allowed workspace root | The data folder sits inside a workspace root | Move one of them |
data_dir_in_use | Another server already uses that data folder | Stop it, or give this server its own MCP_AIC_DATA_DIR |
Only MCP_STUB_SERVER selects the registry; leave other registry variables unset.
Open
Match the code to the fix.
| Code | Cause | Fix |
|---|---|---|
provider_unavailable | The provider program is not installed, or is not one of Claude, Codex, Cursor and Kimi | Check aic_capabilities and install it |
invalid_argument: workspace is not allowed | The folder is outside the allowed roots | Use a folder under a root |
host_not_isolated | The server is not in a container and full host access is not accepted | Ask the operator to prepare a suitable environment; review safety and limits before accepting host access |
policy_unsupported | The provider cannot honour native_tools, or its release was not verified for none | Check the installed release and safety and limits; use a supported provider before accepting broader access or an unverified release |
nested_unavailable | Docker or the nested image is missing | Have the operator restore nested-mode prerequisites; changing to host mode requires an access review |
cap_reached | The session limit is reached | Close a session |
Turns
Stuck, refused or empty.
| Symptom | Cause | Fix |
|---|---|---|
turn_in_progress | A turn is still running | Wait with aic_session_read and await_ms, or aic_turn_cancel |
steer_unavailable | No provider offers steering | Cancel the turn, then send without steer |
| The agent says it has no tools | No registry is reachable by the session | Check MCP_STUB_SERVER and that the registry runs |
not_found for a session that exists | It belongs to another connection, or a reconnect changed your identity | Check the original connection first; list with include_orphaned and resume only when reclaimable |
Fewer events than limit | Read pages use a 16 KiB target budget | Read on with next_since |
When none of these fit, retain the error, session and turn references and ask the operator to check the server log. Inspect partial results and project changes before retrying work. See Safety and limits for what is stored and what a session can reach.