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 stops with a file conflict error

sync only blocks when an untracked file in skills/ or mcp/ matches by name a file being introduced from remote. Untracked files without conflicts are left untouched.

On conflict, sync stops and lists the problematic files. Options:

• publish the conflicting file:

aiman push
aiman sync

• rename or move the conflicting file manually, then retry aiman sync;
• apply the published state and permanently delete the conflicting files:

aiman sync --force

Warning: sync --force permanently deletes conflicting files from the working tree.

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