Weavr

Installation Issues

Node.js version errors

Error: SyntaxError: Unexpected token or similar

Solution: Weavr requires Node.js 22 or later. Check your version with node --version and upgrade if needed.

Build failures

Error: Build fails with TypeScript or bundler errors

# Clean and rebuild
rm -rf node_modules dist
npm install
npm run build
npm run build:web

Configuration Issues

Config file not found

Error: Weavr can't find configuration

# Create config directory and file
mkdir -p ~/.weavr
touch ~/.weavr/config.yaml

# Or run onboard to create it
node weavr.mjs onboard

YAML syntax errors

Error: YAMLException: bad indentation

Solution: YAML is sensitive to indentation. Use spaces (not tabs) and ensure consistent indentation. Use a YAML validator to check your syntax.

CLI Issues

TTY initialization failed

Error: ERR_TTY_INIT_FAILED

Cause: Running in a non-interactive environment (CI, scripts, etc.) 
# Use non-interactive mode
node weavr.mjs onboard --non-interactive --ai-provider anthropic
node weavr.mjs create --non-interactive --name my-workflow --trigger manual
node weavr.mjs ask "Create a workflow" --non-interactive --output workflow.yaml

Command not found

Error: weavr: command not found

Solution: Run Weavr using node weavr.mjs from the project directory, or add an alias to your shell configuration.

Server Issues

Port already in use

Error: EADDRINUSE: address already in use

# Use a different port
node weavr.mjs serve --port 8080

# Or find and kill the process using the port
lsof -i :3847
kill -9 <PID>

Permission denied (EPERM)

Error: listen EPERM

Solution: Run in a terminal with permission to bind to ports. Some restricted environments don't allow binding to ports.

Web UI not loading

Cause: Web UI hasn't been built

# Build the web UI
npm run build:web

# Then start the server
node weavr.mjs serve

Workflow Errors

Workflow not found

Error: Workflow 'name' not found

Solution: Check that the workflow file exists in ~/.weavr/workflows/ and has a .yaml or .yml extension.

Step dependency error

Error: Step 'x' depends on unknown step 'y'

Solution: Check the needs array references existing step IDs. Step IDs are case-sensitive.

Interpolation errors

Error: Cannot read property 'x' of undefined

Solution: Ensure the step you're referencing has completed successfully and the field you're accessing exists in its output.

AI Agent Issues

No API key configured

Error: Anthropic API key not configured

# Set via environment variable
export ANTHROPIC_API_KEY=sk-ant-...

# Or add to config file
# ~/.weavr/config.yaml
anthropicKey: sk-ant-...

Rate limit exceeded

Error: 429 Too Many Requests

Solution: Add delays between requests or upgrade your API plan. Consider using a smaller model for less critical tasks.

Web search not working

Error: Web search API key not configured

# Set a search API key
export BRAVE_API_KEY=your-key
# or
export TAVILY_API_KEY=your-key

Integration Issues

GitHub: gh CLI not found

Error: gh CLI not found

Solution: Install the GitHub CLI from cli.github.com and run gh auth login to authenticate.

GitHub: Not authenticated

Error: gh CLI not authenticated

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

Telegram: Bot token invalid

Error: Unauthorized

Solution: Verify your bot token from @BotFather is correct and hasn't been revoked.

Webhook not receiving events

Cause: Server not publicly accessible

Solution: For local development, use polling mode instead of webhooks. GitHub triggers default to polling mode which uses the gh CLI.

Getting Help

If you're still having issues:

  • Check the GitHub Issues for similar problems
  • Run node weavr.mjs doctor to check your configuration
  • Open a new issue with your error message and steps to reproduce