Troubleshooting

A reference for the most common issues encountered when installing, configuring, and using Weave.

Looking for stable / v0 docs?

If you are using the original OpenCode-only release of Weave (opencode-weave), see the Migrating from v0 guide for v0 config reference. This page covers vNext only.

Weave Didn't Load

Symptom: Your harness starts but Weave agents like Loom or Tapestry aren't available, or the adapter appears to be ignored.

Check these things:

1. Your harness adapter is installed and registered: consult your adapter's getting-started guide. For example, the OpenCode adapter requires a valid opencode.json with the plugin entry:

   {
     "plugin": ["@opencode_weave/weave"]
   }

   Common mistakes:

   • Using "plugins" (plural) instead of "plugin"
   • Missing the array brackets: "plugin": "@opencode_weave/weave" ❌
   • Typo in package name

2. Restart your harness: adapters are loaded at startup. If you added Weave to an already-running instance, restart it.

3. Check for installation errors: your harness may print errors during plugin installation. If you see an npm error referencing the Weave package, check your internet connection or npm registry access.

Agents Not Appearing

Symptom: Weave loaded successfully, but agents you expected to be directly selectable aren't showing in the agent selector.

Check these things:

1. disable agents in your config: check your .weave/config.weave files for a disable agents statement:

   # This would hide the agent
   disable agents ["warp"]

   Remove or comment out the entry to re-enable the agent.

2. For custom agents, naming rules:

   • Name must be lowercase, only letters/numbers/hyphens/underscores
   • Must not collide with built-in names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp)
   • Must start with a letter (not a number)

3. For custom agents, check mode:

   • Custom agents default to mode subagent
   • subagent agents do not appear in the selector
   • Set mode primary or mode all if you want the agent to be directly selectable

4. Config file parses cleanly: an invalid .weave syntax error may cause the entire config to be skipped silently. Check for unmatched braces, unclosed strings, or invalid values.

Config Not Being Applied

Symptom: You've added settings to your .weave config but Weave isn't picking them up.

Check these things:

1. File is at the correct path:

   • Project config: .weave/config.weave (in the project root)
   • Global config: ~/.weave/config.weave

2. Valid .weave syntax: check for:

   • Unmatched braces {}
   • Unclosed quoted strings
   • Unknown keywords

3. Merge precedence: project config (.weave/config.weave) overrides global config for scalar values. If you are setting something in global config but project config overrides it, the global value is ignored.

4. Restart your harness: config is read at startup. Changes to config files require restarting to take effect.

5. Check for silent failures: some config errors (like referencing a non-existent model ID) don't crash Weave but silently fall back to defaults. Check that model IDs are valid for your configured providers.

/start-work Not Working

Symptom: You type /start-work and nothing happens, or you get an error about no plan found.

Check these things:

1. A plan file exists in .weave/plans/: /start-work looks for markdown files with unchecked - [ ] checkboxes:

   ls .weave/plans/

   If the directory is empty, ask Loom to create a plan first by describing a complex task.

2. The plan file has unchecked tasks: if all checkboxes in a plan are already checked (- [x]), there's nothing to execute. /start-work requires at least one - [ ] item.

3. The start-work hook is enabled: check that start-work isn't listed in your disable hooks:

   # This would break /start-work - don't do this
   disable hooks ["start-work"]

4. Plan file follows the expected format: the plan must be a markdown file with GitHub-style task list checkboxes (- [ ] and - [x]). Non-standard checkbox formats won't be recognized.

Tapestry Didn't Continue Automatically

Preview

The automatic continuation settings described in this section are currently in preview. If you need the most predictable behavior, prefer manual resume with /start-work or /run-workflow.

Symptom: You expected execution to resume, but Tapestry stayed idle or stopped after an interruption.

Check these things:

1. Was this compaction recovery or plain idle?

   • By default, Weave resumes after compaction recovery
   • By default, Weave does not nudge a merely idle session to continue

2. Your continuation config:

   continuation {
     recovery { compaction true }
     idle {
       enabled false
       work false
       workflow false
       todo_prompt false
     }
   }

   If idle.work is false, an idle Tapestry session will stay quiet until you run /start-work again.

3. Relevant hooks are enabled:

   • work-continuation controls work recovery and idle work nudges
   • workflow controls workflow continuation behavior

4. The plan is still resumable: /start-work resumes from the first unchecked task. If every checkbox is already checked, there is nothing left to run.

5. Manual resume is always available: if in doubt, run /start-work again.

See Execution & Continuation for the exact rules.

Todos Were or Weren't Finalized Unexpectedly

Symptom: Leftover in_progress todos were silently completed, or you expected a todo-finalization prompt and did not get one.

Check these things:

1. Direct todo repair can happen silently when Weave can write todos directly. This is expected.

2. Fallback todo prompting is separate: if you want a visible prompt when direct write is unavailable, enable:

   continuation {
     idle { todo_prompt true }
   }

3. The todo-continuation-enforcer hook must be enabled. If it is disabled via disable hooks, neither silent repair nor fallback prompting will run.

4. Compaction restoration is separate from todo finalization: compaction-todo-preserver restores todo state after compaction, while todo-continuation-enforcer handles leftover in_progress items.

Skills Not Loading

Symptom: You've assigned skills to agents in config but the agents don't seem to be using them, or you get errors about skills not being found.

Check these things:

1. Skill file is named exactly SKILL.md (uppercase, exact name). Consult your adapter's documentation for the canonical discovery path.

2. Valid YAML frontmatter with a name field:

   ---
   name: react-best-practices
   description: React development guidelines
   ---
   
   # React Best Practices
   ...

   The name field is what you reference in config.

3. Skill name in config matches the frontmatter name:

   agent shuttle {
     skills ["react-best-practices"]
   }

4. Skill is not excluded:

   # Remove from here if present
   disable skills ["react-best-practices"]

Context Window Warnings

Symptom: You see warnings about context window usage during long sessions.

These come from the context-window-monitor hook, which tracks token usage automatically:

• At 80% usage: a warning is printed to help you plan ahead
• At 95% usage: recovery strategies are suggested (e.g., compacting the conversation)

To disable these warnings:

disable hooks ["context-window-monitor"]

See Disabling Features for more about disabling hooks and other components.

Still having issues?

Check the GitHub repository for open issues and discussions. You can also check the Full Configuration Example to see a complete, working config that combines all features.