Skip to content

Troubleshooting

Jump to bottom
Herve Hildenbrand edited this page Jan 20, 2026 · 1 revision

Troubleshooting

Common issues and their solutions.

Installation Issues

"uv: command not found"

Install uv first:

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

# Or via pip
pip install uv

"monocle: command not found"

Monocle needs Rust installed:

# Install Rust if needed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Then install monocle
cargo install monocle

Make sure ~/.cargo/bin is in your PATH.

"bgp-radar: command not found"

bgp-radar needs Go installed:

# Install Go (or use install-deps)
uv run bgp-explorer install-deps

# Or manually
go install github.com/hervehildenbrand/bgp-radar/cmd/bgp-radar@latest

Make sure ~/go/bin is in your PATH.

BGPStream installation fails

BGPStream requires the C library first:

# macOS
brew install bgpstream

# Then Python binding
uv sync --extra bgpstream

On Linux, you may need to build libBGPStream from source. See bgpstream.caida.org.

API Key Issues

"ANTHROPIC_API_KEY not set"

Set your API key:

# Option 1: Environment variable
export ANTHROPIC_API_KEY=your_key_here

# Option 2: .env file
echo "ANTHROPIC_API_KEY=your_key_here" > .env

# Option 3: CLI argument
uv run bgp-explorer --api-key your_key_here chat

"Invalid API key"

Verify your key at console.anthropic.com:

  • Check the key is not expired
  • Ensure you have credits/quota available
  • Confirm you're using the correct key (not a test key)

Connection Issues

"RIPE Stat API error"

RIPE Stat is occasionally slow or unavailable:

  • Wait a few seconds and retry
  • Check stat.ripe.net status
  • The cache (5-minute TTL) reduces repeated failures

"Globalping API error"

Globalping has rate limits:

  • Wait between measurements
  • Register for higher quotas at globalping.io
  • Try with fewer probes or different locations

"No probes available in requested location"

Some locations have limited probe availability:

> Ping 8.8.8.8 from Antarctica
No probes available in the specified location.
Would you like to try from a different location?

Try broader regions or different countries.

PeeringDB data is stale

Refresh the data:

uv run bgp-explorer --refresh-peeringdb chat

This downloads the latest CAIDA dump.

Monitoring Issues

"bgp-radar is not running"

Start monitoring first:

> /monitor start

Or check if bgp-radar is installed:

bgp-radar --help

"bgp-radar not configured"

The bgp-radar binary wasn't found. Either:

  1. Run install-deps to install it:

    uv run bgp-explorer install-deps

  2. Or specify the path:

    uv run bgp-explorer --bgp-radar-path /path/to/bgp-radar chat

Monitoring shows no events

This is normal if nothing unusual is happening. To test:

  1. Check status: /monitor status
  2. Wait for natural events (can take minutes to hours)
  3. Try monitoring more collectors: --collectors rrc00,rrc01,rrc10

Query Issues

"ASN not found"

The ASN might not exist or might have no announcements:

> What prefixes does AS999999 announce?
AS999999 is not announcing any prefixes, or the ASN does not exist.

Try searching by company name instead:

> Search for ASNs from Google

"No routes found for prefix"

The prefix might not be announced globally:

  • Check if it's a private prefix (RFC 1918, etc.)
  • The prefix might be filtered by some networks
  • Try a covering prefix if checking a more-specific

Tool returns error

If a specific tool fails, Claude will note it and continue:

Error getting IXP presence: Connection timeout
Continuing investigation with available data...

This is normal graceful degradation.

Performance Issues

Responses are slow

  • High thinking budget: Lower it with /thinking 4000
  • Network latency: RIPE Stat and other APIs add latency
  • Complex queries: Multi-step investigations take longer

Memory usage is high

  • Clear conversation history: /clear
  • Restart the session
  • Use shorter conversations for simple lookups

Output Issues

Output is truncated

Long outputs are summarized. For full data:

  • Ask for specific items: "Show me the first 20 prefixes"
  • Export to JSON: /export output.json
  • Use --output json for full data

Formatting looks wrong

Ensure your terminal supports UTF-8 and ANSI colors:

# Check terminal settings
echo $TERM
echo $LANG

Try a different terminal emulator if issues persist.

Getting Help

If you can't resolve an issue:

  1. Check for open issues: github.com/hervehildenbrand/bgp-explorer/issues
  2. Open a new issue with:
    • Python version (python --version)
    • OS and version
    • Error message or behavior
    • Steps to reproduce

Next Steps

Clone this wiki locally