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/, mcp/, or loadouts/ 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.

aiman import cannot find an inventory repository

Symptom:

error: no active inventory repository; run 'aiman init' first

aiman import skill and aiman import mcp write only to the active inventory repository, never to the current directory. If you do not have a repository yet, connect one:

aiman init git@github.com:you/aim-loadout.git

If the repository is already cloned locally, make it active:

aiman switch ~/projects/aim-loadout

To check which repository is active, look at the first line of aiman doctor output (Active Repo:).

aiman import reports invalid item name

Symptom:

error: invalid item name "../evil": must not contain "/" or "\"

The command argument is the name of the item in the AI environment (aiman import skill create-spec --from claude-code), not a path to a file. An empty name, ., .., names containing / or \, absolute paths, control characters, and names longer than 255 characters are rejected. To add an item from a file or folder on disk, use aiman add:

aiman add skill ~/Downloads/create-spec.md
aiman add skill ~/Downloads/create-spec

aiman import mcp refuses to import a server

Symptom:

error: MCP server "remote-tool": unsupported transport "http" (only stdio servers can be imported)

AIM manages stdio servers only — those that define a command in the environment config. Servers declared with "type": "http", "type": "sse", or a bare "url" are not imported: previously such a server landed in the inventory as an empty stub with no command, now the command stops and names the reason. Keep that server configured in the AI environment by hand; other servers in the same config are imported as usual.

A script inside an imported skill does not run

Neither transferring a folder skill into the inventory (aiman import skill, aiman add skill <dir>) nor installing a skill into an AI environment preserves file permissions — files are written as 0644. The executable bit on scripts is lost at both steps, so restore it where the script actually runs — in the AI environment directory — and repeat after every aiman apply or aiman sync:

chmod +x ~/.claude/skills/<name>/<script>

Also keep in mind: changes limited to the resource files of a folder skill are not carried over by re-importing — the command compares only SKILL.md and reports already identical. Copy the changed files by hand.

Invalid Skill or MCP Item

Check that:

• the filename matches name;
• the Skill has frontmatter with name and description and a non-empty body after the frontmatter (aiman doctor names the reason: missing name, missing description, empty body);
• the MCP Item contains name, command, args, targets, and env (description is optional both on the MCP Item and on an env variable);
• the YAML is valid.

Formats are described in Inventory Format.

Skill not showing up in the expected AI environment

Symptom: aiman apply/aiman sync complete without errors, but the skill is missing from a specific AI environment.

The cause is almost always the targets field in the skill's frontmatter: if it is set, the skill is installed only into the listed environments. Check:

---
name: my-skill
targets:
  - claude-code
---

Here the skill is delivered only to claude-code, even if both cursor and codex are detected on the machine.

Also keep in mind:

• environment names in targets are not validated — a typo (claud-code instead of claude-code) does not raise an error, the skill simply is not installed anywhere;
• on the additive paths (aiman apply, aiman sync without an active pin), narrowing targets never removes the skill from an environment where it is already installed — only aiman apply --loadout <name> or pinned sync will remove it, and only if the skill is part of the loadout but does not list that environment in its own targets.

To apply a skill to every detected environment, remove the targets field or leave the list empty.

Loadout not found, or missing on another machine

If aiman apply --loadout <name> reports loadout "<name>" not found in loadouts/, check that:

• the file is in loadouts/<name>.yaml in the active inventory repository;
• the name matches either the filename or the name field (spaces and case are normalized: Documentation Work → documentation-work);
• the hint: available loadouts: … line lists the available name values.

If a loadout exists on one machine but not on another, it most likely has not travelled yet: publish it with aiman push on the first machine and pull it in with aiman sync on the second.

aiman sync unexpectedly applies only part of the inventory

Symptom: after aiman sync, environments end up with only some skills and MCP servers instead of the full inventory, and the output starts with applying loadout "X" (pinned).

Cause: a pin is set on this machine (aiman apply --loadout <name> --pin) — sync declaratively applies that loadout instead of the full inventory, including removing items outside its set. This is expected pin behavior, not a bug.

Check the active pin:

aiman status

The Pinned loadout: field shows the name of the pinned loadout, or none. To go back to the full inventory:

aiman apply --default    # apply the full inventory and clear the pin
# or
aiman apply --unpin      # clear the pin without applying anything — the next sync will apply the full inventory

For more on pins, see Concepts and Workflows.

The pin points to a loadout that no longer exists

Symptom:

error: pinned loadout "documentation-work" not found in inventory

aiman sync stops without touching AI environments or updating synced_hash, instead of silently falling back to the full inventory. Typical causes: the loadout was renamed or deleted on another machine and already published, or aiman switch moved to a repository that never had a loadout with that name.

This error is distinct from loadout "X" not found in loadouts/, which apply --loadout returns when no pin is involved — the wording differs deliberately, so the source of the error is easy to tell apart.

What to do:

1. Check which name the loadout currently exists under — aiman status shows the pinned name, and the contents of loadouts/ in the inventory repository show the current names.
2. Clear the pin if you no longer need to apply it:

aiman apply --unpin

3. Or go back to the full inventory:

aiman apply --default

4. Or pin the loadout again under its new name, if it was renamed:

aiman apply --loadout <new-name> --pin

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