Troubleshooting Guide

This guide covers common issues you might encounter when working with Hive and how to resolve them.

Installation Issues

pip install -e . doesn't work

Problem: Running pip install -e . creates a placeholder package and Hive doesn’t function correctly.Solution: Hive uses a uv workspace layout and is NOT installed with pip. Use the quickstart script instead:

./quickstart.sh

Never use pip install to install Hive. Always use the quickstart script.

Python version incompatibility

Problem: Errors related to Python version or syntax.Solution: Hive requires Python 3.11 or higher. Check your version:

python --version

If you have an older version, install Python 3.11+ and ensure it’s in your PATH.

Windows installation issues

Problem: Scripts fail to run on native Windows.Solution: Use WSL (Windows Subsystem for Linux) or Git Bash. If you must use native Windows:

Run PowerShell or Git Bash as administrator
Ensure Python 3.11+ is installed
Disable “App Execution Aliases” in Windows settings:
- Settings → Apps → Advanced app settings → App execution aliases
- Turn off aliases for Python

WSL is the recommended approach for Windows users as it provides the most reliable experience.

uv command not found

Problem: The uv command is not recognized.Solution: The quickstart script installs uv. If it’s missing:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"

Credentials & Authentication

API key not configured

Problem: Errors like “API key not configured” or “credentials not found”.Solution: Run the interactive credential setup:

hive setup-credentials

Or manually add credentials to ~/.hive/credentials (encrypted) or environment variables:

export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"

OAuth token expired or invalid

Problem: “Gmail token expired or invalid” or similar OAuth errors.Solution: Re-authorize the integration:

Visit hive.adenhq.com
Navigate to the integrations page
Re-connect the service (Gmail, Google Docs, etc.)

For Claude Code subscriptions:

// ~/.hive/configuration.json
{
  "use_claude_code_subscription": true
}

Credential store encryption errors

Problem: Errors reading or writing to the encrypted credential store.Solution: Check permissions and encryption key:

# Check directory permissions
ls -la ~/.hive/

# If corrupted, backup and reset
mv ~/.hive/credentials ~/.hive/credentials.backup
hive setup-credentials

Agent Execution Issues

Agent hangs or doesn't respond

Problem: Agent execution appears stuck.Possible causes & solutions:

Waiting for user input (HITL node):
- Check if the agent is waiting for human-in-the-loop input
- Respond to the prompt or cancel the execution
LLM API timeout:
- Check your internet connection
- Verify API keys are valid
- Check LLM provider status page
Infinite loop:
- Check max_node_visits configuration
- Review node edge conditions
- Set a max visits limit:
```
NodeSpec(id="my-node", max_node_visits=10, ...)
```

Deprecated node type errors

Problem: RuntimeError: Deprecated node type 'llm_tool_use'Solution: Migrate to event_loop node type (v0.5.1+):

# Before (v0.5.0)
NodeSpec(node_type="llm_tool_use", ...)

# After (v0.5.1)
NodeSpec(node_type="event_loop", ...)
# or omit (event_loop is now the default)
NodeSpec(...)

Other deprecated types to migrate:

llm_generate → event_loop
function → event_loop with tools
router → event_loop with conditional edges
human_input → HITL in event_loop

Tool not found or not loaded

Problem: Agent can’t access a required tool.Solution:

Check MCP server configuration:

// mcp_servers.json
{
  "hive-tools": {
    "command": "uv",
    "args": ["run", "python", "mcp_server.py", "--stdio"],
    "workdir": "tools"
  }
}

Verify tool is listed:
```
hive info agent-name
```
Check tool credentials:
- Some tools require API keys (e.g., GOOGLE_MAPS_API_KEY)
- Run hive setup-credentials to configure

Memory or state issues

Problem: Agent loses context or state between nodes.Solution: Check isolation levels:

# In agent.py or config.py
RuntimeConfig(
    isolation_level=IsolationLevel.SHARED,  # or ISOLATED, SYNCHRONIZED
    ...
)

ISOLATED: Each execution has its own state
SHARED: State shared across executions in same session
SYNCHRONIZED: Thread-safe shared state

Graph execution fails with null output

Problem: Node fails with “required output key not set”.Solution: Ensure nodes set all required output keys:

NodeSpec(
    id="my-node",
    output_keys=["result"],  # This key MUST be set by the node
    ...
)

In the node implementation, always set output keys:

state.set("result", "value")

Testing Issues

Tests fail with import errors

Problem: ModuleNotFoundError when running tests.Solution: Set PYTHONPATH correctly:

# For agents in exports/
PYTHONPATH=exports uv run python -m agent_name test

# For core framework tests
cd core && pytest tests/ -v

# For tools tests
cd tools && uv run pytest tests/ -v

Test timeouts

Problem: Tests hang or timeout.Solution:

Increase timeout:

# In conftest.py or test file
@pytest.mark.timeout(300)  # 5 minutes
def test_my_agent():
    ...

Use mock mode:

uv run python -m agent_name test --mock

Check for forever-alive agents:
- Forever-alive agents need special test structure
- Don’t call runner.run() directly in tests
- Use runner.start() and runner.stop() instead

LLM judge evaluation failures

Problem: Level 2 (LLM judge) tests fail unexpectedly.Solution:

Check success criteria:

Goal(
    success_criteria=[
        SuccessCriterion(
            description="Clear description of what success looks like",
            weight=1.0,
            metric="llm_judge",  # or output_contains, output_equals
        )
    ]
)

Review conversation history:

# Check logs for full context
cat ~/.hive/sessions/<session-id>/logs/*.log

Adjust threshold:
- Default threshold is 90% weighted score
- May need to adjust criteria weights

Performance Issues

Slow agent execution

Problem: Agent takes too long to execute.Possible optimizations:

Reduce max_tokens:

RuntimeConfig(
    default_model="claude-sonnet-4.5",  # Faster than opus
    max_tokens=8192,  # Lower if appropriate
)

Use faster models:
- Sonnet 4.5 is faster than Opus 4.6
- Consider using different models for different nodes

Enable parallel execution:

RuntimeConfig(
    max_concurrent_executions=5,
)

Review node prompts:
- Shorter, clearer prompts = faster responses
- Remove unnecessary context

High memory usage

Problem: Agent consumes excessive memory.Solution:

Enable checkpoint cleanup:

# In config
checkpoint_store_max_age=3600  # 1 hour

Limit conversation history:
- Conversation memory grows with each interaction
- Consider implementing memory compaction (roadmap item)

Check for memory leaks:

# Monitor memory usage
top -p $(pgrep -f "python.*agent")

Rate limit errors

Problem: “Rate limit exceeded” from LLM provider.Solution:

Add retry logic (built-in for most tools):
- Most Hive tools handle rate limits automatically
- Wait and retry

Reduce concurrent executions:

RuntimeConfig(
    max_concurrent_executions=1,  # Sequential execution
)

Use different API keys:
- Distribute load across multiple keys if available

TUI (Terminal UI) Issues

TUI doesn't display properly

Problem: Text formatting issues or garbled display.Solution:

Check terminal compatibility:
- Use a modern terminal (iTerm2, Alacritty, Windows Terminal)
- Ensure 256-color support:
```
echo $TERM  # Should be xterm-256color or similar
```

Update terminal:

# macOS
brew upgrade iterm2

# Ubuntu/Debian
sudo apt update && sudo apt upgrade

Can't load agent in TUI

Problem: Agent picker doesn’t show agents or load fails.Solution:

Check agent structure:

# Agent must have agent.json
ls exports/my_agent/agent.json

Validate agent definition:
```
hive validate exports/my_agent
```
Check for errors:
```
hive info exports/my_agent
```

Streaming output not showing

Problem: Live streaming pane doesn’t update.Solution:

Ensure you’re using v0.5.1+ (streaming pane added in v0.5.1)
Check that the model supports streaming
Some tools may buffer output

Docker & Deployment Issues

Docker build fails

Problem: Docker image build errors.Solution:

Check Dockerfile location:
```
ls tools/Dockerfile
```

Build with verbose output:

docker build -t hive:latest -f tools/Dockerfile . --progress=plain

Check Docker version:
```
docker --version  # Should be 20.10+
```

Playwright/Chromium issues in Docker

Problem: Browser automation fails in Docker.Solution:

Ensure dependencies are installed:
- Dockerfile includes Playwright Chromium
- Check the official Dockerfile in tools/
Run in headless mode:
- Docker requires headless browser execution
- This is the default for Playwright tools

Webhook server not accessible

Problem: Can’t trigger agent via webhook.Solution:

Check port mapping:
```
docker run -p 8000:8000 hive:latest
```

Verify webhook configuration:

AsyncEntryPointSpec(
    name="webhook",
    type=EntryPointType.WEBHOOK,
    config={"route": "/trigger", "secret": "your-secret"},
)

Test locally:

curl -X POST http://localhost:8000/trigger \
  -H "Content-Type: application/json" \
  -d '{"your": "data"}'

Debugging Tips

Enable Verbose Logging

RuntimeConfig(
    log_level="DEBUG",
)

Check logs in ~/.hive/sessions/<session-id>/logs/

Inspect Session State

# List all sessions
ls ~/.hive/sessions/

# View session logs
cat ~/.hive/sessions/<session-id>/logs/*.log

# Check checkpoints
ls ~/.hive/sessions/<session-id>/checkpoints/

Use Mock Mode

# Test agent without calling real APIs
uv run python -m agent_name run --mock

Check Event Bus

Enable event bus logging to see all agent events:

# Subscribe to all events
event_bus.subscribe(
    EventType.ALL,
    callback=lambda e: print(f"Event: {e.type} - {e.data}")
)

Still Need Help?

Join Discord

Get help from the community

Open an Issue

Report bugs or request features

Read the Docs

Complete documentation

Community

Support

Troubleshooting Guide

Installation Issues

Credentials & Authentication

Agent Execution Issues

Testing Issues

Performance Issues

TUI (Terminal UI) Issues

Docker & Deployment Issues

Debugging Tips

Enable Verbose Logging

Inspect Session State

Use Mock Mode

Check Event Bus

Still Need Help?

Join Discord

Open an Issue

Read the Docs

Build docs developers (and LLMs) love

Community

Support

​Installation Issues

​Credentials & Authentication

​Agent Execution Issues

​Testing Issues

​Performance Issues

​TUI (Terminal UI) Issues

​Docker & Deployment Issues

​Debugging Tips

Enable Verbose Logging

Inspect Session State

Use Mock Mode

Check Event Bus

​Still Need Help?

Join Discord

Open an Issue

Read the Docs

Build docs developers (and LLMs) love

Installation Issues

Credentials & Authentication

Agent Execution Issues

Testing Issues

Performance Issues

TUI (Terminal UI) Issues

Docker & Deployment Issues

Debugging Tips

Still Need Help?