Skip to main content

​
Installation Issues

Problem: curl: Permission denied or similar error.Solution: Use sudo or install to a user directory:
Problem: klaw: command not foundSolution: Ensure /usr/local/bin is in your PATH:
Problem: “klaw cannot be opened because it is from an unidentified developer”Solution:
Or go to System Preferences → Security & Privacy → Allow.

​
Provider Issues

Problem: ANTHROPIC_API_KEY not set or authentication errors.Solutions:
  1. Check the key is set correctly:
  2. Ensure no extra whitespace:
  3. Verify the key is valid at the provider’s dashboard.
Problem: connection refused or timeout errors.Solutions:
  1. Check internet connectivity
  2. Verify no firewall blocking outbound HTTPS
  3. Check provider status page
  4. Try a different provider:
Problem: 429 Too Many Requests or quota errors.Solutions:
  1. Wait and retry
  2. Check your usage at the provider dashboard
  3. Upgrade your plan
  4. Use a different model with lower cost

​
Slack Integration Issues

Problem: Messages to the bot get no response.Checklist:
  1. Is the bot invited to the channel? (/invite @klaw)
  2. Is Socket Mode enabled in Slack app settings?
  3. Are both tokens set?
  4. Check klaw start output for errors
  5. Verify the bot has required OAuth scopes
Problem: Bot takes too long to respond.Solutions:
  1. Check API provider latency
  2. Use a faster model (claude-haiku-3)
  3. Reduce agent skills/tools
  4. Check system resources on the klaw host
Problem: Bot doesn’t see all messages.Solutions:
  1. Ensure channels:history OAuth scope is granted
  2. For private channels, add groups:history
  3. Check Event Subscriptions are enabled
  4. Verify message.channels event is subscribed

​
Distributed Mode Issues

Problem: connection refused when joining controller.Solutions:
  1. Verify controller is running:
  2. Check network connectivity:
  3. Verify token matches
  4. Check firewall rules (port 9090)
  5. Ensure controller is listening on correct interface:
Problem: klaw dispatch hangs or fails.Solutions:
  1. Check if nodes are connected:
  2. Verify agent exists on a node:
  3. Check controller logs for errors
Problem: Nodes show as disconnected intermittently.Solutions:
  1. Check network stability
  2. Increase heartbeat timeout
  3. Check node resource usage (CPU, memory)
  4. Review controller logs for disconnect reasons

​
Container Issues

Problem: klaw build fails.Solutions:
  1. Ensure Podman is installed:
  2. Run from klaw source directory
  3. Check Containerfile exists
  4. Verify disk space
Problem: klaw run fails immediately.Solutions:
  1. Build the image first:
  2. Check if image exists:
  3. Check container logs:

​
General Issues

Problem: Settings in config.toml are ignored.Solutions:
  1. Check config file location:
  2. Validate TOML syntax (no errors)
  3. Environment variables override config
  4. Run klaw config view to see effective config
Problem: klaw using excessive memory.Solutions:
  1. Reduce conversation history length
  2. Clear old sessions:
  3. Use a smaller model
  4. Restart klaw to clear memory
Problem: Cryptic error messages.Solutions:
  1. Enable debug logging:
  2. Check logs:
  3. Report issue on GitHub with logs

​
Getting Help

If you can’t resolve your issue:
  1. Check GitHub Issues for similar problems
  2. Join the Discord community
  3. File a new issue with:
    • klaw version (klaw version)
    • OS and architecture
    • Steps to reproduce
    • Relevant logs