Troubleshooting¶

Common issues and solutions for Hawkeye MCP.

Installation Issues¶

Command Not Found: hawkeye-mcp¶

Problem: hawkeye-mcp: command not found

Solutions:

1. Check installation:

   npm list -g hawkeye-mcp-server
   

2. Reinstall globally:

   npm install -g hawkeye-mcp-server
   

3. Use npx instead:

   npx hawkeye-mcp-server
   

Node Version Error¶

Problem: Error: Node.js 20+ required

Solution:

# Check version
node --version

# Upgrade Node.js
# macOS
brew install node@20

# Linux
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Authentication Issues¶

401 Unauthorized¶

Problem: Authentication failed: 401 Unauthorized

Solutions:

1. Verify credentials:

   # Check environment variables
   echo $HAWKEYE_EMAIL
   

2. Test login:

3. Try logging into Hawkeye web UI

4. Reset password if needed

5. Check for typos:

6. No extra spaces
7. No surrounding quotes

8. Correct email format

9. For remote server:

10. Verify your access token is valid and not expired
11. Check the remote server URL is correct

Connection Timeout¶

Problem: ECONNREFUSED or ETIMEDOUT

Solutions:

1. Check network:

   curl https://app.neubird.ai/api/health
   

2. Check firewall:

3. Allow outbound HTTPS (443)

4. Check corporate proxy settings

5. For remote server:

6. Verify the remote server URL is reachable
7. Check with your administrator

Claude Desktop Issues¶

Tools Not Showing¶

Problem: Can't see Hawkeye tools in Claude Desktop

Solutions:

1. Verify config file location:

   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   type %APPDATA%\Claude\claude_desktop_config.json
   

2. Check JSON syntax:

3. Use JSONLint
4. Look for missing commas

5. Check bracket matching

6. Restart Claude Desktop:

7. Completely quit (Cmd+Q on macOS)
8. Wait 3 seconds

9. Relaunch

10. Check logs:

    # macOS
    tail -f ~/Library/Logs/Claude/mcp*.log
    
    # Look for errors
    

MCP Server Crashes¶

Problem: MCP server keeps crashing

Solutions:

1. Test server directly:

   npx @modelcontextprotocol/inspector npx hawkeye-mcp-server
   

2. Check credentials:

3. Ensure all env vars are set

4. No special characters causing issues

5. Update package:

   npm update -g hawkeye-mcp-server
   

Investigation Issues¶

Investigation Takes Too Long¶

Problem: Investigation running for several minutes

Normal Duration: 30-90 seconds

If Longer:

1. First investigation on new project:
2. Initial sync takes 5-10 minutes

3. Subsequent investigations faster

4. Check connection sync:

   Show me connection status
   

5. Complex incident:

6. Many data sources = longer time
7. This is normal

Investigation Progress Issues¶

Status Shows 'unknown'¶

Problem: Investigation status returns 'unknown' or no progress data

Solutions:

1. Investigation just started:
2. Wait 5-10 seconds for stream to initialize

3. Check again: Show me the investigation status

4. Stream connection initializing:

5. Normal during first few seconds

6. Progress data will appear shortly

7. Investigation hasn't started yet:

8. Verify investigation was created successfully
9. Check session UUID is correct

No Steps Showing¶

Problem: investigation_summary.steps is empty or undefined

Solutions:

1. Early initialization phase:
2. Investigation may be in early setup
3. Chain of thought messages haven't arrived yet

4. Wait 30 seconds and check again

5. Investigation just completed:

6. Use hawkeye_get_chain_of_thought for full step details

7. Use hawkeye_get_rca for final results

8. Check investigation age:

9. Progress data is cleaned up after 1 hour
10. For older investigations, use other tools like get_chain_of_thought

Progress Stuck at Same Percentage¶

Problem: Progress percentage hasn't changed in several minutes

This is Normal When:

1. Complex data queries:
2. Some steps require heavy database queries
3. Analysis phase often takes longer

4. May pause at 30-60% during correlation analysis

5. Large data sets:

6. Processing many logs or metrics

7. Normal for thorough investigations

8. Pattern detection:

9. ML-based analysis can take time
10. Expected behavior

Concerning If:

1. Stuck at 0% for >2 minutes:
2. Investigation may have failed to start
3. Check connection sync status

4. Try creating a new investigation

5. Stuck at same % for >5 minutes:

6. Check investigation status for errors
7. Look for error messages in status response
8. Contact support if issue persists

Very Few Data Sources¶

Problem: unique_sources only shows 1-2 sources, expected more

Solutions:

1. Check connection sync:

   Show me project connections
   # Ensure all are in SYNCED state
   

2. Verify data availability:

   Show me available resources for this project
   # Check if expected log/metric sources exist
   

3. Time range issues:

4. Incident may be outside data retention period

5. Check if data exists for the incident timeframe

6. Connection permissions:

7. Verify IAM/API key permissions
8. Ensure connections can access all resources

Current Step Not Updating¶

Problem: current_step field shows same message for several checks

Solutions:

1. Check progress_percentage:
2. If increasing, investigation is progressing
3. current_step updates at major milestones only

4. Check completed_steps instead

5. Long-running step:

6. Some steps naturally take longer
7. Analysis and diagnosis phases especially

8. Normal behavior

9. Investigation may be done:

10. Check status field for "completed"
11. Get final RCA: Show me the RCA

Incomplete RCA¶

Problem: RCA lacks details or specific recommendations

Solutions:

1. Add context instructions:

   Create a SYSTEM instruction with our architecture details
   

2. Add investigation steps:

   Create RCA instructions for common incident types
   

3. Verify connections:

   Show me project connections
   # Ensure all are SYNCED
   

4. Check data availability:

   Show me available resources for this project
   

Incorrect Root Cause¶

Problem: RCA identifies wrong root cause

Solutions:

1. Ask follow-up questions:

   Why do you think that's the root cause?
   What other possibilities exist?
   

2. Add clarifying instruction:

   Create an instruction to guide this type of investigation better
   

3. Test instruction first:

4. Apply to past session
5. Rerun investigation
6. Compare results

Connection Issues¶

Connection Won't Sync¶

Problem: Connection stuck in SYNCING state

Solutions:

1. Check status:

   Show me connection details for [connection-uuid]
   

2. Verify credentials:

3. AWS: Check role ARN and external ID
4. Datadog: Check API/app keys

5. Azure: Check all 4 credentials

6. Check permissions:

7. AWS: ReadOnlyAccess policy

8. Ensure trust relationship correct

9. Wait longer:

10. First sync: 5-10 minutes normal
11. Large environments: up to 15 minutes

Missing Resources¶

Problem: Expected resources not showing in discoveries

Solutions:

1. Check sync status:

   Wait for connection to sync completely
   

2. Verify region:

3. AWS: Ensure region included in connection

4. Resources in unconfigured regions won't show

5. Check permissions:

6. Missing permissions = missing resources
7. Verify IAM policies

Performance Issues¶

Slow Responses¶

Problem: Claude responses taking long time

Solutions:

1. Use compact mode:

   Show me sessions in compact format
   

2. Limit results:

   Show me only last 10 sessions
   

3. Use global install:

   npm install -g hawkeye-mcp-server
   # Faster than npx
   

High Memory Usage¶

Problem: MCP server using too much memory

Solutions:

1. Restart MCP server:

2. Restart Claude Desktop

3. Limit concurrent operations:

4. Investigate one alert at a time

5. Update to latest version:

   npm update -g hawkeye-mcp-server
   

Error Messages¶

"No uninvestigated incidents found"¶

Meaning: All alerts have been investigated OR filters are removing them

Solutions:

1. Expand time range:

   Show uninvestigated alerts from last 30 days
   

2. Check filters:

   Show me active FILTER instructions
   

3. Include all severities:

4. Your filter might be too aggressive

"Session not found"¶

Problem: Session UUID not found

Solutions:

1. Verify UUID:
2. Check for typos

3. Use correct UUID format

4. Check project:

5. Ensure using correct project

6. Session might be in different project

7. List sessions:

   Show me all sessions
   

"Connection not synced"¶

Problem: Connection not ready for use

Solution:

Wait for connection [uuid] to finish syncing

Debug Mode¶

Enable Verbose Logging¶

In Claude Desktop config:

{
  "mcpServers": {
    "hawkeye": {
      "command": "npx",
      "args": ["-y", "hawkeye-mcp-server"],
      "env": {
        "HAWKEYE_EMAIL": "...",
        "HAWKEYE_PASSWORD": "...",
        "HAWKEYE_LOG_LEVEL": "debug"
      }
    }
  }
}

Using MCP Inspector¶

Test server in isolation:

npx @modelcontextprotocol/inspector npx hawkeye-mcp-server

Opens web interface showing: - Available tools - Tool execution - Request/response logs - Errors

Getting Help¶

If issues persist:

1. Check logs:

   # macOS
   tail -100 ~/Library/Logs/Claude/mcp*.log
   

2. Test with inspector:

   npx @modelcontextprotocol/inspector npx hawkeye-mcp-server
   

3. Contact support:

4. Email: support@neubird.ai

5. Include: Error message, logs, MCP version

6. Documentation:

7. Installation Guide
8. FAQ