This page covers common issues you may encounter when using Weave, along with their causes and solutions.

Error: Config file not found

or

Error: No config file found at .weave/config.weave

Weave cannot locate a configuration file in the expected locations. This typically happens when:

• You have not run weave init yet
• The config file is in the wrong location
• The config file has the wrong name (must be config.weave, not config.weave.txt or similar)

1. Initialize Weave configuration:

   weave init --scope local --yes

   This creates .weave/config.weave in your project root.

2. Verify the file exists:

   ls .weave/config.weave

3. Check the file name: The config file must be named exactly config.weave (not config.weave.txt, weave.config, or any other variation).

Related documentation: CLI Reference - weave init, DSL Configuration - Configuration Locations

3:12: unexpected token '}', expected identifier

or

5:1: unclosed block

or

2:8: unterminated string literal

The DSL parser encountered invalid syntax. Common causes include:

• Missing closing braces }
• Unterminated string literals (missing closing quote)
• Invalid block structure
• Unexpected characters

1. Check the line and column indicated in the error message. The format is line:column: message.

2. Common syntax mistakes:

   Missing closing brace:

   agent loom {
     temperature 0.5
   # Missing closing brace here

   Fix:

   agent loom {
     temperature 0.5
   }

   Unterminated string:

   agent loom {
     description "Orchestration coordinator
   }

   Fix:

   agent loom {
     description "Orchestration coordinator"
   }

   Missing block name:

   agent {
     temperature 0.5
   }

   Fix:

   agent loom {
     temperature 0.5
   }

3. Validate your config:

   weave validate

Related documentation: DSL Configuration, Agents

Error: Prompt file not found: custom-agent.md

or

Error: Could not resolve prompt file: loom.md

Weave cannot locate the prompt file specified in prompt_file. This happens when:

• The prompt file does not exist in .weave/prompts/
• The prompt_file value includes a directory path (not allowed)
• The file name is misspelled

1. Verify the prompt file exists:

   ls .weave/prompts/

2. Check the file name in your config:

   agent custom-agent {
     prompt_file "custom-agent.md"
   }

3. Ensure the file is in the correct directory:

   • Project scope: .weave/prompts/
   • Global scope: ~/.weave/prompts/

4. Use bare filenames only:

5. Create the missing prompt file:

   echo "# Custom Agent Prompt" > .weave/prompts/custom-agent.md

Related documentation: DSL Configuration - Prompt File Resolution, Agents

opencode debug config doesn’t list Weave’s agents (loom, tapestry, shuttle, and so on) under agent, or opencode debug info doesn’t show the Weave adapter among its plugins.

OpenCode loads Weave from the plugin list in opencode.json or opencode.jsonc. Common causes:

• The adapter isn’t in the plugin list, or the package name is misspelled
• The entry is in plugins (plural) or names @weaveio/weave-adapter-opencode2. Those are for OpenCode 2; see Adapter not loading (OpenCode 2)
• The plugin points at a file instead of the package (for example dist/index.js)
• The legacy @opencode_weave/weave plugin is still listed alongside the adapter
• OpenCode wasn’t restarted after the plugin list changed

1. Check the plugin list in your project’s opencode.json or opencode.jsonc, and in ~/.config/opencode/:

   {
     "plugin": ["@weaveio/weave-adapter-opencode@0.2.0"]
   }

   The package name is @weaveio/weave-adapter-opencode. OpenCode fetches it when it starts, so there’s no separate npm install step.

2. Remove the legacy plugin @opencode_weave/weave if it’s listed. See Upgrading from legacy Weave.

3. Restart OpenCode, then check:

   opencode debug config

4. Read the adapter log. The adapter writes to .weave/weave.log in your project (set WEAVE_LOG_FILE to change the path). Config and prompt errors appear there.

5. Validate your config from the project root. Agents the adapter can’t register are reported by name:

   weave validate

Related documentation: Install for OpenCode, CLI Reference - Harness detection and installation

opencode2 starts, but the agent list has no loom, tapestry, shuttle, and so on, and new sessions don’t start on Loom.

OpenCode 2 loads Weave from the plugins list (plural) in opencode.jsonc or opencode.json. Common causes:

• The entry is in plugin (singular). That’s OpenCode 1.x’s key, and OpenCode 2 doesn’t load it.
• The entry names the OpenCode 1.x package, @weaveio/weave-adapter-opencode, instead of @weaveio/weave-adapter-opencode2.
• The entry has no version. That installs npm latest; before 0.2.0 that was an adapter that registers no agents on OpenCode 2.0.
• The entry combines a version with a subpath, such as @weaveio/weave-adapter-opencode2@0.2.0/server.
• The plugin is still installing. On the first start the agents can take up to a minute to appear.

1. Check the plugins list in your project’s opencode.jsonc or opencode.json, and in ~/.config/opencode/:

   {
     "plugins": ["@weaveio/weave-adapter-opencode2@0.2.0"]
   }

2. Wait a minute and restart opencode2 if this is the first start after adding the plugin.

3. Validate your config from the project root. If Weave’s status reports an invalid config, this names the problem:

   bunx @weaveio/weave-cli@0.2.0 validate

Related documentation: Install for OpenCode 2

Claude Code starts, but the agent list has no weave:loom, weave:shuttle, and so on, or the main agent isn’t Loom.

Claude Code loads Weave from two plugin directories that weave compose generates in your project. Common causes:

• Claude Code was started without both --plugin-dir flags
• weave compose --adapter claude-code --init hasn’t been run in this project, so .weave/plugins/claude-code/ doesn’t exist
• The weave CLI isn’t installed globally, so the bootstrap plugin’s SessionStart hook can’t regenerate the agents (the hook reports [weave] compose skipped)

1. Generate the plugins from the project root:

   weave compose --adapter claude-code --init

2. Start Claude Code with both plugin directories:

   claude --plugin-dir ./weave-bootstrap-plugin --plugin-dir ./.weave/plugins/claude-code

3. Install the CLI globally if the hook can’t find it:

   bun add --global @weaveio/weave-cli@0.2.0

4. Validate your config. Agents that can’t be generated are reported by name:

   weave validate

Related documentation: Install for Claude Code, CLI Reference - Harness detection and installation

Weave does not run harness runtimes directly.

and weave run exits with code 1.

weave run is not a valid command. Weave configures harnesses but does not run them directly.

1. Initialize Weave configuration:

   weave init --scope local --yes

2. Launch your harness using its native command:

   • OpenCode: opencode
   • OpenCode 2: opencode2
   • Claude Code: claude --plugin-dir ./weave-bootstrap-plugin --plugin-dir ./.weave/plugins/claude-code

3. Verify your config is loaded:

   weave validate
   weave prompt list

Related documentation: CLI Reference - No runtime execution, Quickstart

⚠  Migration warnings — the following legacy fields were skipped:

  • skill_directories: legacy skill_directories are not migrated; move or symlink those skills into a directory your harness discovers (for OpenCode, .opencode/skills/)
  • custom_agents.code-reviewer.triggers: legacy structured triggers ({ domain, trigger }) are not migrated; add string triggers to the agent if Loom should route to it
  • categories.backend.patterns: patterns are removed; describe routing with category description and string triggers
  • workflows: legacy workflow definitions are not supported in migration v1; define workflows using the current DSL workflow syntax

weave init migrate found legacy fields that have no equivalent in the current DSL. This is expected: migration converts what it can and reports the rest.

Migration warnings don’t stop the migration. The config file is written, the command exits with code 0, and the same warnings are recorded as comments at the top of the migrated config.weave.

1. Review each warning. Common ones:

   • skill_directories: move or symlink the skills into .opencode/skills/.
   • disabled_tools: use tool_policy on the agent or category instead.
   • Custom agent triggers: add string triggers to the agent.
   • Category patterns: categories route by description and triggers. See Routing.
   • workflows: define workflows with the DSL workflow syntax.
   • Agent name collisions: rename a custom agent that reuses a builtin name (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp).
   • Custom agent with no prompt: add a prompt or prompt_file to the agent in config.weave.

2. Validate your migrated config from the project root:

   weave validate

3. Inspect agent prompts:

   weave prompt list
   weave prompt inspect loom

Related documentation: Upgrading from legacy Weave, CLI Reference - weave init migrate

config.weave:[agents.loom.temperature] Too big: expected number to be <=2

or

config.weave:[agents.custom.mode] Invalid option: expected one of "primary"|"subagent"|"all"

or, for configs written for Weave 0.1.x:

config.weave:[categories.backend] Unrecognized key: "patterns"
config.weave:[categories.backend.description] Invalid input: expected string, received undefined
config.weave:[agents.loom.triggers.0] triggers must contain quoted strings

The config file contains values that fail schema validation. Common causes:

• Fields removed in Weave 0.2.0: category patterns and object triggers. Every category also needs a description. See Categories.
• Invalid enum values (e.g., mode "worker" instead of mode subagent)
• Out-of-range numbers (e.g., temperature 3 when max is 2)
• Wrong value types (e.g., string instead of number)

1. Check the validation error message for the field path and expected value.

2. Fix the invalid value:

   Invalid enum:

   agent custom {
     mode worker  # Invalid
   }

   Fix:

   agent custom {
     mode subagent
   }

   Out-of-range number:

   agent loom {
     temperature 3  # Invalid (max is 2)
   }

   Fix:

   agent loom {
     temperature 0.7
   }

3. Validate your config:

   weave validate

Related documentation: DSL Configuration, Tool Policy

[agent.custom.tool_policy.unknown_tool] Unrecognized key

or

Error: Invalid tool policy capability

The tool_policy block contains invalid tool names or capability values. Common causes:

• Harness-specific tool names (e.g., call_weave_agent) that cannot be mapped to abstract capabilities
• Typos in tool names
• Invalid capability values (must be allow, deny, or ask)

1. Use only recognized tool policy capabilities:

   tool_policy {
     read allow
     write allow
     execute allow
     delegate deny
     network ask
   }

2. Remove harness-specific tool names:

Do not use harness-specific tool names like call_weave_agent, read_file, write_file, etc. Use abstract capabilities instead: read, write, execute, delegate, network. :::

3. Validate your config:

   weave validate

Related documentation: DSL Configuration - Tool Policy, Tool Policy

If you encounter an issue not covered here:

1. Check the error message for line and column numbers, then inspect your config at that location.
2. Validate your config with weave validate to get detailed error messages.
3. Review the documentation:
   • DSL Configuration for syntax and structure
   • CLI Reference for command usage
   • Agents for agent configuration
   • Tool Policy for tool permissions
4. Check the GitHub repository for known issues and discussions.