Project-Local Troubleshooting

Diagnose project-local bundle issues

Project-Local Troubleshooting

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Common failures and how to fix them. Pair with the agent-owned doctor operation which surfaces most of these automatically.

Manifest validation errors

"Bundle in .aiwg/extensions/ must declare type: \"extension\""

The manifest's `type` field must match the parent directory it lives in. A bundle under `.aiwg/extensions/foo/` must declare `"type": "extension"`, not `"addon"` or `"framework"`.

Fix: edit the `type` field, or move the bundle to the matching directory:

mv .aiwg/extensions/foo .aiwg/addons/foo   # if you meant addon

"kebab-case alphanumeric, no leading/trailing hyphen"

Bundle ids must match `^a-z0-9?$`.

RejectedWhyFix
`Foo`uppercase`foo`
`foo_bar`underscore`foo-bar`
`-foo` / `foo-`leading/trailing hyphen`foo`
`café`non-ASCII`cafe`

"type 'addon' requires addonConfig"

Each bundle type requires its matching nested config block:

`type`Required block
`addon``addonConfig`
`framework``frameworkConfig`
`plugin``pluginConfig`
`extension``extensionConfig` (optional — extensions may omit)

Fix: add the missing block. The simplest valid stubs:

"addonConfig":     { "entry": { "skills": "skills/" } }
"frameworkConfig": { "path": "src/" }
"pluginConfig":    { "payloadType": "addon", "payloadPath": "payload/" }

Or scaffold a fresh bundle and copy the structure: the agent-owned new-bundle operation.

"<= 64 KB" / "<= 200 bundles per project"

The threat model (#1042) sets DoS limits. If you're hitting these you almost certainly want one of:

  • A single addon containing many artifacts, instead of many tiny extensions
  • Compressing your manifest (the schema doesn't need verbose comments)
  • Filing a fresh issue if your real use case needs higher limits

"must be a relative path (no leading slash, no ..)"

Path-traversal is refused at validation time. Entry paths (`addonConfig.entry.skills`, `frameworkConfig.path`, `pluginConfig.payloadPath`) must be relative paths under the bundle.

Rejected: `../../etc/foo`, `/abs/path`, `safe/../escape` Fix: use a clean relative path: `skills/`, `src/`, `payload/`.

Shadow / override warnings

"Refused to shadow safety-critical upstream..."

Your bundle exports an artifact with the same id as an upstream safety-critical artifact. AIWG refuses to deploy without an explicit acknowledgement.

Fix (intentional override): add the artifact id to your manifest's `overrides` array:

{
  "id": "my-overrides",
  "type": "extension",
  "overrides": ["human-authorization"],
  ...
}

Re-deploy: the agent-owned use operation. The override is logged as `shadow-acknowledged` in `.aiwg/activity.log` and surfaced prominently in the agent-owned doctor operation.

Fix (accidental): rename your artifact id so it doesn't collide.

"Phantom override: 'X' declared in manifest.json but no upstream artifact has that id"

The id in your `overrides` array doesn't match any upstream artifact. Either you typo'd, the upstream artifact was renamed, or you're declaring overrides defensively for things that don't exist.

Fix: remove the phantom entry, or correct the id.

"Duplicate project-local <type> 'X' also exported by: <other-bundle>"

Two of your project-local bundles each export an artifact with the same type+id. AIWG refuses both — there's no winner.

Fix: rename the artifact in one of the bundles, or delete the duplicate.

Drift detection

"Drift (N): foo :: rules/r1.md @ claude (deployed file differs from source)"

The deployed file at the provider path has a different SHA-256 than the source `.aiwg/<type>/<name>/rules/r1.md` recorded at deploy time. This usually means:

  • An operator hand-edited the deployed file (most common)
  • Another tool overwrote it
  • The source file changed since the last the agent-owned use operation

Fix: re-deploy to overwrite the deployed file with the current source:

Use AIWG to complete this documented outcome: Fix: re-deploy to overwrite the deployed file with the current source
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Or, if you want to keep the deployed edits and discard the bundle source, copy them back:

Use AIWG to complete this documented outcome: Or, if you want to keep the deployed edits and discard the bundle source, copy them back
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

"(some entries lack artifactHashes — re-run the agent-owned use operation to record)"

Older deploys don't have `artifactHashes` recorded. The drift detector can't run on those entries until they're re-deployed.

Fix: the agent-owned use operation to refresh the registry entry with hashes.

Remove failures

"Refused: bundle already exists at .aiwg/extensions/foo/" (from new-bundle)

You can't scaffold over an existing bundle.

Fix: pick a different name, or remove the existing one first:

Use AIWG to complete this documented outcome: Fix: pick a different name, or remove the existing one first
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

"Some artifacts skipped (see above). Use the force option to override mutation refusal."

the agent-owned remove operation detected operator-edited deployed files (case 2 from the design) and refused to delete them by default to avoid losing your edits.

Fix (you really want them gone):

Use AIWG to complete this documented outcome: Fix (you really want them gone)
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The `.aiwg/<type>/<name>/` source is still preserved — the force option only overrides the case-2 prompt, not the source-preservation invariant.

"owned by '<other-bundle>' — refusing to delete"

The deployed file at the path your bundle would target is registered as owned by another project-local bundle. AIWG refuses to delete content that belongs to another bundle, even with the force option.

Fix: if you really want to take ownership, the agent-owned remove operation first, then the agent-owned remove operation.

Promote failures

"destination-exists: 'agentic/code/addons/foo' already exists"

the agent-owned promote operation refuses to overwrite. Either you've promoted this bundle before, or the upstream has an unrelated artifact with the same id.

Fix: remove the destination first, then re-promote:

Use AIWG to complete this documented outcome: Fix: remove the destination first, then re-promote
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

"project-local-references: rules/r1.md, +2 more"

Your bundle contains ``@.aiwg/...`` references that would dangle once the bundle moves to upstream (where `.aiwg/` is the project-output dir, not a bundle-source dir).

Fix (preferred): edit the references to use upstream-safe paths: `@$AIWG_ROOT/...` for upstream content, or in-bundle relative paths.

Fix (escape hatch): the agent-owned promote operation — promotes anyway, but the references will be broken in the destination. Only useful when you plan to fix them up after the copy.

"hash mismatch on rules/r1.md after copy. Rolled back."

The copy step succeeded but the SHA-256 of the destination didn't match the source. AIWG rolled back the destination directory. This shouldn't happen on a normal filesystem — usually it means another process wrote to the destination during the copy.

Fix: investigate concurrent writes (e.g., a watcher script, another shell session). Re-run promote once the source is undisturbed.

Activity log issues

"activity-log auto-append failed (non-fatal): ..."

The lifecycle event couldn't be written to `.aiwg/activity.log`. This is non-blocking — your operation still succeeded. Common causes:

  • Read-only filesystem
  • `.aiwg/` directory permissions
  • Storage backend misconfigured

Fix: the agent-owned storage operation to see the configured backend; check write permissions on `.aiwg/`.

Discover events spam the log

`emitDiscoverEventsDeduped` deduplicates against the recent log tail by `(name, type)` to prevent this. If you're still seeing duplicates:

  • Your bundle id changed, so the dedupe key changed
  • The log was rotated or truncated

Both are fine — the log will stabilize after the next round of normal operations.

See also