Troubleshooting
Resolve common configuration, Git safety, composition, and collision errors.
Project output is dirty
agentsmith will not overwrite a modified, staged, conflicted, untracked, or ignored destination. Review the file and either commit the intended version or move it out of the generated path. There is no project --force option.
For a newly generated output, add and commit it before the next generation.
Global output is unmanaged or changed
Run asmith global diff. If you intentionally want agentsmith to adopt or recover the paths, run asmith global generate --force. This updates the external hash state after writing.
Source Repository is not clean
global sync rejects tracked, staged, conflicted, and nonignored untracked source changes. Commit, stash, or remove them before syncing. Ignored local source such as *.local.md is allowed.
Git pull cannot fast-forward
global sync uses only git pull --ff-only. Resolve divergence manually in the Source Repository, then rerun the command. agentsmith will not merge or rebase on your behalf.
Missing slot contribution
A required-slot received no snippet from the selected packs. Add a contribution under the matching pack slot directory, select the intended pack, or change the directive to an optional slot.
Contribution targets an absent slot
A selected pack has content for a slot the template or enabled skill does not declare. This is usually a mismatched template/pack combination or a misspelled slot name.
Skill name collision
Two skills visible from the same working location share a public name. asmith project explain shows generated skill sources. Rename or disable one source, or remove the conflicting unmanaged skill. agentsmith does not silently choose a winner.
Codex override shadows generated context
Remove or relocate AGENTS.override.md at the planned scope before generation. Codex gives that file precedence, so generating AGENTS.md there would be misleading.
Size budget warning
Use asmith project explain or asmith global explain to inspect artifact and effective-chain sizes. Reduce duplicated material, move reusable workflow detail into an on-demand skill, or intentionally raise the corresponding budget.
Diagnose without writing
asmith project lint
asmith project explain --json
asmith project diffThese commands are safe to use while investigating because they do not write generated artifacts.