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

Error: OpenCode adapter not found

or

Warning: Weave config detected but not loaded

The OpenCode harness cannot locate or load the Weave adapter. Common causes:

• Wrong key name in opencode.jsonc (must be "weave", not "weave-config" or similar)
• The adapter is not installed
• The adapter path is incorrect

1. Check your opencode.jsonc or opencode.json file:

   {
     "weave": {}
   }

   The key must be exactly "weave".

2. Verify the adapter is installed:

   npm list @weaveio/weave-opencode-adapter

3. Reinstall the adapter if needed:

   npm install @weaveio/weave-opencode-adapter

4. Run weave init to configure the adapter:

   weave init --harness opencode --yes

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

Error: Claude Code adapter not found

or

Warning: Weave config detected but not loaded

The Claude Code harness cannot locate or load the Weave adapter. Common causes:

• Missing --plugin-dir flag in Claude Code launch command
• The adapter is not installed
• The adapter path is incorrect

1. Verify the adapter is installed:

   npm list @weaveio/weave-claude-code-adapter

2. Reinstall the adapter if needed:

   npm install @weaveio/weave-claude-code-adapter

3. Add the --plugin-dir flag when launching Claude Code:

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

4. Run weave init to configure the adapter:

   weave init --harness claude-code --yes

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

Error: Pi adapter not found

or

Warning: Weave config detected but not loaded

The Pi harness cannot load the Weave adapter. Common causes:

• Pi version is too old (Weave requires Pi 1.5.0 or later)
• Pi is running in health-only mode (adapter loading is disabled)
• The adapter is not installed

1. Check your Pi version:

   pi --version

   Weave requires Pi 1.5.0 or later.

2. Upgrade Pi if needed:

   npm install -g @pi/cli

3. Verify Pi is not in health-only mode:

   Check your Pi config for health_only: true. If present, remove it or set it to false.

4. Run weave init to configure the adapter:

   weave init --harness pi --yes

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

Error: 'weave run' is not supported

or

Use 'weave init' and harness-specific launch commands instead

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 or code (depending on your installation)
   • Claude Code: claude-code
   • Pi: pi

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:

  • workflows: legacy workflow definitions are not supported in migration v1
  • continuation: legacy continuation settings are not supported in migration v1
  • custom_agents.loom: "loom" collides with a builtin agent name

The migration tool encountered legacy fields that cannot be automatically converted to the current DSL. This is expected behavior for certain fields.

Migration warnings do not prevent the migration from succeeding. The config file is still written successfully.

1. Review the warnings to understand which fields were skipped.

2. Manually add skipped fields if needed:

   • Workflows: Define workflows using the current DSL syntax. See DSL Configuration - Workflows.
   • Continuation: Use the current DSL continuation block if needed.
   • Agent name collisions: Rename custom agents that collide with builtin names (loom, tapestry, shuttle, pattern, thread, spindle, weft, warp).

3. Validate your migrated config:

   weave validate

4. Inspect agent prompts:

   weave prompt list
   weave prompt inspect loom

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

[agent.loom.temperature] Expected number between 0 and 2, received 3

or

[agent.custom.mode] Invalid enum value. Expected 'primary' | 'subagent', received 'worker'

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

• 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.