Troubleshooting

This guide covers common issues you may encounter with LumenFlow and how to resolve them.

Gate Failures

Format check fails

Symptom:

> Format check... FAILED
>   src/utils/validator.ts needs formatting

Fix:

# Auto-fix formatting
pnpm format
# or
npx prettier --write .
# Or fix only the files listed by gates (copy from the gates output):
pnpm prettier --write "apps/docs/src/content/docs/getting-started/quickstart.mdx"

# Then retry
pnpm wu:prep --id WU-XXX

Lint check fails

Symptom:

> Lint check... FAILED
>   src/api/handler.ts:42 - Unexpected any

Fix:

1. Read the error message to understand the issue
2. Fix the code (don’t disable the rule unless necessary)
3. Retry: pnpm wu:prep --id WU-XXX

Common lint fixes:

| Error | Fix | | ----------------------- | -------------------------------------- | | no-explicit-any | Add proper TypeScript types | | no-unused-vars | Remove the variable or prefix with _ | | exhaustive-deps | Add missing useEffect dependencies | | no-restricted-imports | Use the correct import path |

Type check fails

Symptom:

> Type check... FAILED
> error TS2322: Type 'string' is not assignable to type 'number'

Fix:

1. Fix the first error (later errors often cascade from earlier ones)
2. Save and check again
3. Repeat until clean

Tip

TypeScript errors cascade. Fix them one at a time, starting from the first.

Tests fail

Symptom:

> Tests... FAILED
>   FAIL src/__tests__/auth.test.ts
>   Expected: "success"
>   Received: "error"

Fix:

1. Run the failing test in isolation: pnpm test src/__tests__/auth.test.ts
2. Debug: check test setup, mocks, and assertions
3. Fix and retry

Common causes:

• Mocks not reset between tests (use beforeEach)
• Async tests not awaited
• Environment differences (CI vs local)

Pre-existing gate failures

If gates fail on code you didn’t change:

1. Verify the failure existed before your changes

   # Save your changes as a patch
   git diff > /tmp/wu-changes.patch
   
   # Verify on clean main
   git restore .
   pnpm gates
   # If it fails here, it's pre-existing
   
   # Re-apply your changes
   git apply /tmp/wu-changes.patch

2. Use a named gate skip only when the gate is explicitly skippable

   pnpm wu:done --id WU-042 \
     --skip-gate lane-health \
     --reason "Pre-existing lint failure in src/legacy.ts" \
     --fix-wu WU-050

3. Create a follow-up WU to fix the issue

Caution

Never skip gates for failures you introduced. Fix them first.

WU State Issues

WU stuck in in_progress

Symptom: WU shows in_progress but worktree is gone or work is done elsewhere.

Fix:

# Check current state
pnpm wu:status --id WU-042

# Recover based on situation
pnpm wu:recover --id WU-042

# Choose the appropriate action:
pnpm wu:recover --id WU-042 --action restore  # Recreate missing active worktree from lane branch
pnpm wu:recover --id WU-042 --action resume   # Reconcile, keep work
pnpm wu:recover --id WU-042 --action reset    # Reset ready/in_progress → ready
pnpm wu:recover --id WU-042 --action cleanup  # Remove orphaned worktree

Use restore first when the WU is active or recently active and its lane branch still exists. It recreates the worktree without resetting WU status, branch, baseline/main metadata, or completion evidence. Use reset for orphaned ready / in_progress state only after restore is impossible or intentionally not wanted.

--action reset refuses on done WUs

In recent versions, wu:recover --action reset --force will refuse to run when a completion stamp exists at .lumenflow/state/packs/software-delivery/stamps/WU-XXXX.done. Resetting a done WU used to silently discard its completion metadata and was the root cause of the “YAML says ready, stamp says done” drift you may see on older WUs.

If you see “stale metadata” — WU YAML status is ready but the stamp file exists — use wu:repair instead, which detects the inconsistency and restores the done status without touching the stamp:

pnpm wu:repair --id WU-042        # repairs a single WU
pnpm wu:repair --all --check      # dry-run audit across every WU
pnpm wu:repair --all              # repair every drift issue

The --action reset path is now the right tool only for orphaned ready or in_progress WUs — not for un-completing a done WU. If you genuinely need to undo a completion (rare), delete the stamp file manually first, then re-run the reset command.

WU status mismatch

Symptom: backlog.md says one status, WU YAML says another.

Fix:

# Check for state inconsistencies
pnpm wu:repair --all --check

# Fix detected inconsistencies (regenerates backlog.md and status.md from state store)
pnpm wu:repair --all

Lane already has a WU in progress

Symptom:

ERROR: Lane "Framework: Core" already has WU-040 in progress

Fix:

1. Check if WU-040 is truly in progress: pnpm wu:status --id WU-040
2. If blocked, mark it: pnpm wu:block --id WU-040 --reason "Waiting for API"
3. If done, complete it: pnpm wu:done --id WU-040
4. If orphaned, recover: pnpm wu:recover --id WU-040 --action reset

Lane lock not auto-clearing despite dead PID

Symptom:

ERROR: Lane "Framework: Core" is locked by WU-040 (since 2026-02-19T10:00:00Z)

The lock holder’s process is no longer running, but the lock is not auto-cleared.

Explanation: Lane locks persist after the wu:claim process exits. A dead PID alone does not trigger auto-clearing — the lock must also be older than 2 hours (stale). This prevents a second claim from stealing a legitimately held lane.

Fix:

1. If the lock is recent (less than 2 hours old), it is likely still valid. Complete or release the existing WU first.
2. If the lock is genuinely abandoned, unlock manually:

pnpm wu:unlock-lane --lane "Framework: Core" --reason "Abandoned lock"

3. Locks older than 2 hours with a dead PID will auto-clear on the next wu:claim attempt.

Evidence-only state drift during wu:done

Symptom:

ERROR: Worktree has uncommitted changes. Cannot proceed with wu:done.

But git status shows only .lumenflow/state/packs/software-delivery/wu-events.jsonl as modified (from a recent wu:brief run).

Cause: Running wu:brief records evidence to wu-events.jsonl. If other WUs merged to main and triggered auto-rebase, the rebase could fail because this workflow-generated file was dirty.

Fix: As of v3.19.0, wu:done auto-rebase automatically preserves and restores wu:brief evidence when wu-events.jsonl is the only dirty file. If you’re on an older version, commit the evidence file before retrying:

cd worktrees/<lane>-wu-xxx
git add .lumenflow/state/packs/software-delivery/wu-events.jsonl
git commit -m "wu(wu-xxx): preserve wu:brief evidence"
cd /path/to/repo
pnpm wu:done --id WU-XXX

Ownership violation on wu:block or wu:release

Symptom:

❌ SESSION OWNERSHIP VIOLATION: Active session is attached to another WU.

or:

❌ CLAIM OWNERSHIP VIOLATION: WU-XXX was claimed by a different session.

Cause: As of v3.19.0, state-mutating commands validate session ownership. You’re trying to modify a WU that belongs to another agent session.

Fix:

1. Don’t modify another agent’s WU to free a lane. Wait for the owning WU to complete or block itself.
2. If you have legitimate reason for cross-session recovery, use the override:

pnpm wu:block --id WU-XXX --override-owner --reason "Manual recovery per team decision"

All overrides are audited to .lumenflow/ownership-override-audit.log.

Worktree Issues

Worktree not found

Symptom:

ERROR: Worktree not found for WU-042

Fix:

# If WU should still be in progress and the lane branch exists, restore first
pnpm wu:recover --id WU-042 --action restore

# If restore is impossible and the WU is genuinely orphaned, reset + reclaim
pnpm wu:recover --id WU-042 --action reset
pnpm wu:claim --id WU-042 --lane "Framework: Core"

# If WU is done but worktree lingers
pnpm wu:recover --id WU-042 --action cleanup

Changes made in wrong directory

Symptom: You made changes in main instead of the worktree.

Fix:

# From main checkout, save a patch
git diff > /tmp/main-changes.patch

# Move to worktree and apply
cd worktrees/framework-core-wu-042
git apply /tmp/main-changes.patch

# Clean main
cd /path/to/main
git restore .

# Commit in worktree
cd worktrees/framework-core-wu-042
git add .
git commit -m "wu(wu-042): implement feature"

Worktree has merge conflicts

Symptom: Conflicts after rebasing the worktree branch.

Fix:

cd worktrees/framework-core-wu-042

# Resolve conflicts in each file
git status  # See conflicting files
# Edit files to resolve conflicts
git add <resolved-files>
git rebase --continue

Tip

Prefer small WUs to minimize conflict risk. Large WUs that touch many files are more likely to conflict with parallel work.

Git Issues

wu:done fails with “not a fast-forward”

Symptom:

ERROR: Cannot fast-forward merge lane/framework-core/wu-042 to main

Cause: Main has new commits since you started your WU.

Fix:

cd worktrees/framework-core-wu-042
git fetch origin main
git rebase origin/main
# Resolve any conflicts
git push --force-with-lease origin lane/framework-core/wu-042

# Return to main and retry
cd /path/to/repo
pnpm wu:done --id WU-042

wu:done fails with “Worktree has uncommitted changes”

Symptom:

ERROR: Worktree has uncommitted changes. Cannot proceed with wu:done.

Cause: wu:done requires a clean, committed worktree before it can merge.

Fix:

cd worktrees/<lane>-wu-xxx
git status
git add .
git commit -m "wu(wu-xxx): describe the change"

# Return to main and retry
cd /path/to/repo
pnpm wu:done --id WU-XXX

If the changes were accidental, restore the files, then retry.

Hooks block my commit

Symptom:

ERROR: WU commit attempted from main checkout

Cause: You’re trying to commit WU work from the main directory.

Fix:

# Move to the worktree
cd worktrees/framework-core-wu-042
git add .
git commit -m "wu(wu-042): implement feature"

Commit message missing WU ID

Symptom:

BLOCKED: Commit message must reference WU-123

Fix: Include the WU ID in the commit message, for example:

git commit -m "wu(wu-1305): document workflow friction"

Branch drift warning

Symptom:

WARNING: Branch is 15 commits behind origin/main

Fix:

cd worktrees/framework-core-wu-042
git fetch origin main
git rebase origin/main

Parallel completions detected

Symptom:

⚠️  PARALLEL COMPLETIONS DETECTED

Cause: Other WUs merged to main while your WU was in progress.

Fix: Rebase your worktree onto main, then retry:

cd worktrees/<lane>-wu-xxx
git fetch origin main
git rebase origin/main
cd /path/to/repo
pnpm wu:done --id WU-XXX

Metadata rebase audit appears after wu:done

When wu:done resolves governed metadata conflicts during an automatic rebase, LumenFlow appends an audit row to .lumenflow/meta-rebase-audit.ndjson. The file is append-only local evidence. It is intentionally ignored by Git and remains on disk across lumenflow init and lumenflow:upgrade.

Do not commit the audit and do not delete it to satisfy gates. Incremental format checks exclude only this exact normalized runtime path because Prettier does not parse NDJSON; changed source files are still formatted and checked normally. If an older workspace shows the file as untracked, run lumenflow:upgrade to reconcile .gitignore. Reconciliation adds the canonical ignore entry without deleting or rewriting existing audit bytes.

Software Delivery State Namespace

As of the state-namespace migration (WU-3378), Software Delivery state (the WU event log, stamps, archive, merge lock, telemetry, flow log, incidents, and commands log) resolves under a pack-owned namespace instead of generic shared .lumenflow/<name> paths:

.lumenflow/state/packs/software-delivery/
├── wu-events.jsonl          # WU lifecycle event log
├── stamps/                  # WU completion stamps
├── archive/                 # archived WU events
├── merge.lock                # wu:done merge coordination lock
├── telemetry/                # gates, DORA, costs, tools, etc.
├── flow.log                  # WU flow events
├── incidents/                 # agent incident records
├── commands.log                # git command audit log
└── migration-complete.json    # durable migration sentinel (do not edit)

Agent session state (.lumenflow/sessions/) stays at the shared kernel path — it’s a cross-pack contract with the agent-runtime pack and is not part of this namespace.

Detection and migration: every CLI command checks for the sentinel file above before running main(). If it’s missing and legacy .lumenflow/state, .lumenflow/stamps, etc. exist, LumenFlow runs a one-way, atomic migration: it copies the legacy content into the namespace through a private staging directory, then promotes it with a single atomic rename, then records the sentinel (source digest, target schema version, per-category file counts — no secrets). The legacy directories are never deleted or written back to — they remain on disk as a historical record. Once the sentinel exists, subsequent CLI invocations skip re-verification (a single file-existence check), so steady-state startup cost is unaffected.

Recovery: the migration is fail-closed. If it’s interrupted mid-run, the next invocation either resumes cleanly (a crash before the atomic promote just leaves disposable scratch space that gets cleared) or finalizes cleanly (a crash after the promote but before the sentinel just needs the sentinel written — no data is re-copied or duplicated). If it detects the legacy source has changed since a prior successful migration (tampering or manual edits), or that the target namespace already contains data that doesn’t match what the legacy source would produce, it refuses to proceed and leaves both locations untouched — inspect .lumenflow/state/packs/software-delivery/ manually before retrying.

Removal: lumenflow:uninstall cleans up both the new namespace and any remaining legacy directories.

Configuration: workspace.yaml’s software_delivery.state.* fields (all except base, the kernel-shared .lumenflow root) may still be overridden, but overrides must resolve inside the pack namespace — an override that points outside .lumenflow/state/packs/software-delivery is rejected at startup instead of silently redirecting state to a shared writer path.

CLI Issues

Command not found: wu-create

Symptom:

bash: wu-create: command not found

Fix:

# Ensure CLI is installed
pnpm add -D @lumenflow/cli

# Use npx if not in PATH
npx wu-create --help

# Or add scripts to package.json

Config validation errors

Symptom:

ERROR: Invalid workspace.yaml
  - lanes.definitions[0].name must match pattern "^[A-Za-z]+: [A-Za-z]+"

Fix:

1. Check the error message for the specific field
2. Compare with the Configuration Reference
3. Fix the YAML syntax or values

Validate without running:

pnpm validate

Memory checkpoint fails

Symptom:

ERROR: Cannot create checkpoint - no session active

Fix:

# Initialize memory for this WU
pnpm mem:init --wu WU-042

# Then checkpoint
pnpm mem:checkpoint --wu WU-042

wu:done warns about missing checkpoints

Symptom:

⚠️  No checkpoints found for WU-XXX session.

Fix: Create checkpoints during long sessions:

pnpm mem:checkpoint --wu WU-XXX

Context Validation Errors

LumenFlow commands include context-aware validation that checks your location, WU status, and git state before running. When validation fails, you’ll see an error with a copy-paste fix.

WRONG_LOCATION

Symptom:

ERROR: WRONG_LOCATION - wu:done must be run from main checkout
FIX: cd /home/user/repo && pnpm wu:done --id WU-042

Fix: Run the command from the correct location. wu:done runs from main; wu:prep runs from the worktree.

WRONG_STATUS

Symptom:

ERROR: WRONG_STATUS - WU-042 is in 'ready' status, expected 'in_progress'

Fix: Claim the WU first: pnpm wu:claim --id WU-042 --lane "Your Lane"

GIT_DIRTY

Symptom:

ERROR: GIT_DIRTY - Worktree has uncommitted changes

Fix: Commit your changes before running wu:prep:

cd worktrees/lane-wu-xxx
git add .
git commit -m "wu(wu-xxx): describe changes"

Configuring Validation

You can adjust validation behavior in workspace.yaml:

software_delivery:
  experimental:
    context_validation: true # Enable validation (default: true)
    validation_mode: 'warn' # 'off' | 'warn' | 'error'
    show_next_steps: true # Show guidance after success

Enforcement Hooks

pnpm lumenflow:integrate is a deprecation no-op as of WU-3543 — it prints migration guidance and exits 0 without writing any files. LumenFlow no longer generates or manages AI-client-specific enforcement hooks. If your project has a .claude/hooks/ directory from an older LumenFlow version, it is a snapshot — your file now, never regenerated or touched by LumenFlow again. Adapting an enforcement-hook layer into your own tool is a repo-owner task; see AI Coding Assistant Integrations for a copyable example.

If a hook blocks your operation, check:

1. Are you in a worktree? Hooks block edits outside worktrees. Run pwd and verify.
2. Do you have a claimed WU? Some hooks require an active WU for edits.
3. Is the file in your code_paths? Hooks may restrict edits to scoped files.

See Agent Safety for the full enforcement architecture.

Bootstrap And Local Runtime Prerequisites

Clean WU worktrees may not have packages/@lumenflow/cli/dist built locally. Root LumenFlow package scripts should route through node tools/cli-entry.mjs <entry> so commands can use an existing main checkout dist or build on demand instead of failing with MODULE_NOT_FOUND.

If a package script edit adds or changes LumenFlow CLI aliases, run:

pnpm verify:script-help
pnpm verify:script-help --run-probes

The live probes cover common agent entry points such as mem:create, orchestrate:monitor, lumenflow:commands, and lumenflow:setup-prereqs.

Before local database or local model workflows, run:

pnpm lumenflow:setup-prereqs
pnpm lumenflow:setup-prereqs --json

The report checks Supabase CLI, Docker, and Supabase local stack readiness when Supabase config or deps are detected. It also checks Ollama binary, OpenAI-compatible local API, and configured model readiness when Ollama deps or OLLAMA_* env vars are present.

Official setup references:

• Supabase local development
• Supabase CLI getting started
• Ollama API introduction
• Ollama OpenAI compatibility

The prereq report intentionally omits local service keys and token-shaped values. Do not paste raw supabase start, .envrc, or provider-token output into issues, WU notes, or prompts.

Still Stuck?

If these solutions don’t help:

1. Check logs: cat .lumenflow/state/packs/software-delivery/flow.log
2. Run with debug: DEBUG=lumenflow:* pnpm wu:done --id WU-042
3. Review the FAQ for common pitfalls.

Include in your question:

• The exact error message
• Your workspace.yaml (redact secrets)
• Output of pnpm wu:status --id WU-XXX
• Your Node.js version: node --version