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 skip-gates with documentation

   pnpm wu:done --id WU-042 \
     --skip-gates \
     --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 resume   # Reconcile, keep work
pnpm wu:recover --id WU-042 --action reset    # Reset to ready
pnpm wu:recover --id WU-042 --action cleanup  # Remove orphaned worktree

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

Worktree Issues

Worktree not found

Symptom:

ERROR: Worktree not found for WU-042

Fix:

# If WU should be in progress, re-claim
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-1305

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

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 .lumenflow.config.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 exec lumenflow 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

Still Stuck?

If these solutions don’t help:

1. Check logs: cat .lumenflow/flow.log
2. Run with debug: DEBUG=lumenflow:* pnpm wu:done --id WU-042
3. Ask for help:
   • GitHub Discussions
   • Discord

Include in your question:

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