Troubleshooting

Check overall state

aiman status
aiman doctor

status answers "what has changed and what is published." doctor answers "is the local machine ready to apply inventory."

AI environment not found

Symptom:

environment codex not found

Steps:

1. Verify the AI tool is installed.
2. Check the standard environment directory.
3. If the path is non-standard, set it in aim.local.yaml.

environments:
  codex: ~/.codex

aiman sync blocked by local changes

aiman sync will not overwrite local changes without an explicit decision from you.

Options:

• publish changes:

aiman push
aiman sync

• manually save or discard local changes;
• apply the published state, discarding local changes:

aiman sync --force

Remote repository is ahead of local state

If push reports that the remote is ahead, apply the published state first:

aiman sync

Then redo your local changes or publish the current state.

Required MCP env variable is not set

Symptom:

required env variable API_KEY is missing

Run aiman sync — AIM will prompt for the value interactively. Or set it directly in aim.local.yaml:

mcp_env:
  context7:
    API_KEY: "..."

Do not commit aim.local.yaml.

Invalid Skill or MCP Item

Check that:

• the filename matches name;
• the Skill has a non-empty body after the frontmatter;
• the MCP Item contains name, description, command, args, targets, and env;
• the YAML is valid.

Formats are described in Inventory Format.

No access to the remote repository

Check:

• SSH key or HTTPS authentication;
• repository access permissions;
• the presence of the origin remote;
• network connectivity.

Git history has diverged

AIM intentionally does not perform merges on your behalf.

If the history has diverged, restore the repository using standard Git commands manually, then retry:

aiman status
aiman sync