Troubleshooting

Known failure modes and how to recover from them. Organised by where the symptom appears.

Installation

npm ERR! 401 Unauthorized when installing Foundry or alloy

Foundry and alloy are published to GitHub Packages, not the public npm registry. The 401 means npm can't authenticate.

Check:

1. Your .npmrc has the right block:

   @engineering11:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. The token has read:packages scope (create one at https://github.com/settings/tokens).

3. The token belongs to a user with access to the engineering11 organisation's packages.

Project-level .npmrc overrides user-level ~/.npmrc. If your project has its own .npmrc without the registry line, that's the culprit.

Installer asks for a Node version

Foundry requires Node.js >= 20. Check with node --version. Use nvm install 20 or your platform's package manager to upgrade.

"An installation already exists" prompt is unexpected

The installer detects .foundry/ in the cwd. If one is there from a different project (e.g. you ran installs in nested directories), it'll surface as an existing install. Either pick a fresh --directory, or run uninstall to clear the old one first.

Knowledge layer

[alloy] @engineering11/alloy is not installed.

The skill:e11-knowledge halts with this message when alloy isn't in node_modules/. Run:

npm install @engineering11/alloy

from the project root and retry. This affects Architect, UX, Dev, Bootstrapper, and Analyst's [TR] Technical Research — all of which halt cleanly until alloy is installed.

NOT FOUND in corpus for a doc that should exist

Two common causes:

1. Wrong tier. A query like sdk:datastores smart-routes to the Tier-2 sdk base first; if no doc exists there, it falls back to the Tier-1 backend-api base. If even that's missing, you might be on an older alloy version, or the corpus is out of the skill's supported range (it halts rather than misreading a moved tree). Check the installed corpus version in node_modules/@engineering11/alloy/package.json and the pin in .alloy/corpus.lock.
2. Wrong subdoc name. Tier 2 uses backend-using / frontend-using / etc.; Tier 1 uses using / building. Smart routing usually handles this, but explicit api:<name>:using is the safer bet for Tier 1 docs.

The four reserved upstream-skill keys fail

The pattern:backend-shared / pattern:backend-standards / pattern:gen-microservice / pattern:gen-sdk keys resolve via skill:e11-sdks-nodejs, which clones the sdks-nodejs repo to a local cache.

• No network or auth. The clone fails silently; the skill reports it. Confirm you can git clone https://github.com/engineering11/sdks-nodejs independently, or set a local $CLONE_PATH override.

• Older branch. The skill expects .claude/skills/<file>.md to exist. If your clone is on a branch before those skills landed, run git pull in the clone, or delete the cache and let the skill re-clone:

  rm -rf ~/.foundry/cache/sdks-nodejs

Scaffold workflows

"Target directory is not empty, refusing to scaffold"

The bootstrap wizard refuses to write into a non-empty output_root. Pick a fresh path or clean the existing target (verify it doesn't contain work you want to keep, first).

Interrupted wizard — how to resume

State persists at {project-root}/.foundry/_scaffold/wizard-state.yaml. Restart with:

@e11-bootstrapper RI

It reads the state file and resumes from the last completed step. If you want a clean start instead, delete the state file.

"Scaffold workflow not found"

The scaffold workflows under 5-scaffold/ ship with Foundry, but if you're on an old version some may be missing. Run npx @engineering11/e11-foundry install with the update option to bring them in. Check npx @engineering11/e11-foundry status to see installed versions.

Implementation phase

Dev halts saying "ALLOY PRE-LOAD FAILED for sdk:<pkg>"

Dev pre-loads alloy for every @engineering11/* SDK before editing code. When a referenced SDK has no alloy doc, it halts and asks how to proceed:

• [R]ead the package source at node_modules/@engineering11/<pkg>/src and continue.
• [S]kip the convention check for this SDK only.
• [A]scalate to Architect to document the gap.

This is by design — it surfaces real gaps rather than letting Dev guess. Don't suppress the halt; pick the right choice for the situation.

Story tasks not marked complete despite implementation

Dev's critical actions forbid marking a task [x] unless implementation and tests pass. If a task stays [ ]:

1. Check the test suite — npm test. Failing tests mean the task can't be checked off.
2. Check the task has its own test. If a task was implemented but no test was written, Dev pauses to add one before marking complete.
3. Check the story file's File List — every changed file must be tracked.

If everything looks complete and the task is still [ ], ask Dev to "review the open tasks in story <slug>".

Code Review finds nothing despite obvious issues

[CR] Code Review is most useful in a fresh context with a strong model. If you run it in the same session that wrote the code, the model has confirmation bias.

Open a new agent session, ideally with a higher-capability model, and re-run:

@dev CR on story 2.3

Tests detect a different framework than your project uses

QA reads scripts.test from package.json to detect the framework. If detection is wrong:

• Confirm scripts.test is set correctly and points to the framework binary.
• Confirm the framework is in devDependencies.
• For monorepos, run QA from the package directory that has the right package.json.

QA refuses to introduce a new test framework. If you don't have one yet, install it manually first.

Tool integrations

Skills don't appear in Claude Code / Codex / OpenCode

After install, the tool may need a restart to pick up new skill files. Quit and re-open the tool.

If skills still don't appear:

1. Check the right target directory exists:
   • Claude Code: .claude/skills/
   • Codex / Cursor: .agents/skills/
   • OpenCode: .opencode/skills/
2. Check there's no ancestor conflict. If a Foundry install exists in a parent directory (e.g. ~), the project install may have been skipped to avoid ambiguity. Either remove the ancestor install or use the existing one.
3. Re-run npx @engineering11/e11-foundry install with the update action — skills are copied verbatim as directories; the update re-lays them down.

status shows installed but tool doesn't see anything

npx @engineering11/e11-foundry status

shows installed modules, the layout (runtime scripts, central config, override files), and per-tool skill counts. If status says claude-code is installed but .claude/skills/ is empty, re-run install with the update action.

Customization & overrides

An override isn't applying

Work through these in order — they cover nearly every case:

1. Wrong file name / layer. The override must be named for the skill directory: .foundry/custom/e11-agent-pm.toml, not pm.toml or agent-pm.toml. Personal variants end .user.toml. Check what the skill actually resolves:

   node .foundry/scripts/resolve-customization.mjs --skill .claude/skills/<skill> --key agent   # or --key workflow

2. Wrong top-level table. Agent-skills read [agent]; workflow skills read [workflow]. A [workflow] block in an agent override merges fine — and is never read.

3. Wrong field name. The surface is exactly what the skill's customize.toml declares. Fields it doesn't declare are carried but ignored — the resolver won't warn. Compare against the installed skill's customize.toml.

4. Wrong merge-mode expectation. Scalars override; persistent_facts / activation_steps_* / principles append (you can't remove shipped entries — neutralize instead); keyed arrays (code/id) replace only on an exact key match — a typo'd id silently appends a second entry instead of replacing. See the merge table.

5. Malformed TOML. A parse error in an optional layer is a warning on stderr, and resolution proceeds without that layer — easy to miss. Run the resolver by hand and read stderr.

6. Still stuck? Run e11-customize ([CF]) in audit mode — it reads your overrides, verifies via the resolver, and points at the exact field.

resolve-customization.mjs / resolve-config.mjs missing or failing

Skills don't brick without the resolver — every skill documents the manual fallback: read customize.toml (base) → .foundry/custom/<skill>.toml → <skill>.user.toml and merge by the standard rules. If you're seeing the fallback, fix the cause:

• Scripts missing from .foundry/scripts/ → your install is from an earlier release or was partial. Re-run npx @engineering11/e11-foundry install (update).
• Node < 20 → the scripts require Node ≥ 20 (node --version).
• Exit code 1 with "customize.toml not found" → the --skill path is wrong; point it at the installed skill directory (the one containing customize.toml).

Headless & automation

A headless run stalls or asks a question

• Only some skills are headless-safe: e11-dev-auto, e11-spec-flow, and the skills that document a headless mode (e11-prfaq --headless, e11-product-brief, e11-discovery). Interactive skills driven by e11 agent on a headless runtime (e.g. claude -p) get no human at their gates — the model decides and proceeds. For supervised runs use --runtime print and paste steps into a live session.
• e11-dev-auto requires subagent support; without it, it HALTs blocked with condition no subagents rather than degrading.

Reading an unattended outcome

Don't parse conversation output. e11-dev-auto writes {implementation_artifacts}/e11-dev-auto-result.json (status, spec_file, blocking_condition, followup_review_recommended) and mirrors status into the spec file's frontmatter with details under ## Auto Run Result. blocked + unclear intent / intent gaps means the intent needs sharpening — re-run with a tighter prompt or a spec file; it will never guess.

e11 agent picks the wrong agent flavor

The runner prefers agent-skills (a skills-dir entry whose customize.toml carries [agent]) and falls back to legacy compiled agents only while an older install is mid-upgrade. If a stale compiled agent is being picked up, finish the upgrade: re-run install and check the migration report (Upgrading Foundry).

Generic recovery

When in doubt:

1. status to confirm what's actually installed.
2. install with the update action to refresh everything — your .foundry/custom/ overrides are never touched.
3. uninstall then install as a last resort. Preserves your {planning_artifacts}/, {implementation_artifacts}/, and {project_knowledge}/ artifacts.

The [BH] e11-help skill is also always available — it can suggest next steps for a stuck state if you describe the symptom.

Source

CLI commands: tools/cli/commands/ · installer config: tools/cli/installers/lib/ide/platform-codes.yaml · help skill: e11-help/SKILL.md.