Troubleshooting

Solutions for common Headroom issues including proxy startup, connection errors, no token savings, high latency, and installation problems.

Solutions for common Headroom issues.

Proxy Server Issues

Proxy will not start

Symptom: headroom proxy fails or hangs.

# Check if port is already in use
lsof -i :8787

# Try a different port
headroom proxy --port 8788

# Check for missing dependencies
pip install "headroom-ai[proxy]"

# Run with debug logging
headroom proxy --log-level debug

Connection refused when calling proxy

Symptom: curl: (7) Failed to connect to localhost port 8787

# Verify proxy is running
curl http://localhost:8787/health

# Check if proxy started on a different port
ps aux | grep headroom

Proxy returns errors for some requests

Symptom: Some requests work, others fail with 502/503.

# Check proxy logs for the actual error
headroom proxy --log-level debug

# Verify API key is set
echo $OPENAI_API_KEY   # or ANTHROPIC_API_KEY

# Test the underlying API directly
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

No Token Savings

Symptom: stats['session']['tokens_saved_total'] is 0.

Diagnosis:

stats = client.get_stats()
print(f"Mode: {stats['config']['mode']}")          # Should be "optimize"
print(f"SmartCrusher: {stats['transforms']['smart_crusher_enabled']}")

Common causes:

Mode is audit (observation only, no modifications)
Messages do not contain tool outputs
Tool outputs are below the 200-token threshold
Data is not compressible (high uniqueness, code, grep results)

Solutions:

import {  } from 'headroom-ai';

// Ensure the proxy is running in optimize mode
// (default, unless --no-optimize was passed)
const  = await (messages, { : 'gpt-4o' });
.(`Saved: ${.tokensSaved} tokens`);
.(`Compressed: ${.compressed}`);

# 1. Ensure mode is "optimize"
client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",  # NOT "audit"
)

# 2. Or override per-request
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    headroom_mode="optimize",
)

# 3. Lower the compression threshold
config = HeadroomConfig()
config.smart_crusher.min_tokens_to_crush = 100  # Default is 200

Compression Too Aggressive

Symptom: LLM responses are missing information that was in tool outputs.

# 1. Keep more items
config = HeadroomConfig()
config.smart_crusher.max_items_after_crush = 50  # Default: 15

# 2. Skip compression for specific tools
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    headroom_tool_profiles={
        "important_tool": {"skip_compression": True},
    },
)

# 3. Disable SmartCrusher entirely
config.smart_crusher.enabled = False

High Latency

Symptom: Requests take longer than expected.

Diagnosis:

import time
import logging

logging.basicConfig(level=logging.DEBUG)

start = time.time()
response = client.chat.completions.create(...)
print(f"Total time: {time.time() - start:.2f}s")

Solutions:

# 1. Use BM25 instead of embeddings (faster)
config = HeadroomConfig()
config.smart_crusher.relevance.tier = "bm25"

# 2. Increase threshold to skip small payloads
config.smart_crusher.min_tokens_to_crush = 500

# 3. Disable transforms you don't need
config.cache_aligner.enabled = False
config.rolling_window.enabled = False

Installation Issues

pip install fails with C++ compilation error

Symptom: RuntimeError: Unsupported compiler -- at least C++11 support is needed!

# Linux / Debian-based (including Docker)
apt-get install -y build-essential && pip install headroom-ai

# macOS (Xcode command line tools)
xcode-select --install && pip install headroom-ai

For Docker, install and remove build tools in one layer:

FROM python:3.11-slim
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
    && pip install "headroom-ai[proxy]" \
    && apt-get purge -y build-essential && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/*

ModuleNotFoundError: No module named 'headroom'

# Check it is installed in the right environment
pip show headroom-ai

# If using virtual environment, ensure it is activated
source venv/bin/activate

# Reinstall
pip install --upgrade headroom-ai

Missing optional dependency

# For proxy server
pip install "headroom-ai[proxy]"

# For embedding-based relevance scoring
pip install "headroom-ai[relevance]"

# For code compression (tree-sitter)
pip install "headroom-ai[code]"

# For everything
pip install "headroom-ai[all]"

Provider-Specific Issues

OpenAI: Invalid API key

import os
from openai import OpenAI

api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY not set")

client = HeadroomClient(
    original_client=OpenAI(api_key=api_key),
    provider=OpenAIProvider(),
)

Anthropic: Authentication error

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
client = HeadroomClient(
    original_client=Anthropic(api_key=api_key),
    provider=AnthropicProvider(),
)

Unknown model warnings

# For custom/fine-tuned models, specify context limit
client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    model_context_limits={
        "ft:gpt-4o-2024-08-06:my-org::abc123": 128000,
        "my-custom-model": 32000,
    },
)

ValidationError on Setup

result = client.validate_setup()
print(result)

# Common issues:
# {"provider": {"ok": False, "error": "No API key"}}
#   -> Set OPENAI_API_KEY or pass api_key to OpenAI()
#
# {"storage": {"ok": False, "error": "unable to open database"}}
#   -> Check path permissions, use :memory: for testing
#
# {"config": {"ok": False, "error": "Invalid mode"}}
#   -> Use "audit" or "optimize" only

For testing, use in-memory storage:

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    store_url="sqlite:///:memory:",
)

Debugging Techniques

Enable Full Logging

import logging

# See everything
logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s %(name)s %(levelname)s %(message)s",
)

# Or just Headroom logs
logging.getLogger("headroom").setLevel(logging.DEBUG)

Use Simulation to Inspect Transforms

plan = client.chat.completions.simulate(
    model="gpt-4o",
    messages=messages,
)

print(f"Tokens: {plan.tokens_before} -> {plan.tokens_after}")
print(f"Transforms: {plan.transforms_applied}")
print(f"Waste signals: {plan.waste_signals}")

import json
print(json.dumps(plan.messages_optimized, indent=2))

Test Transforms Directly

from headroom import SmartCrusher, Tokenizer
from headroom.config import SmartCrusherConfig
import json

config = SmartCrusherConfig()
crusher = SmartCrusher(config)
tokenizer = Tokenizer()

messages = [
    {
        "role": "tool",
        "content": json.dumps({"items": list(range(100))}),
        "tool_call_id": "1",
    }
]

result = crusher.apply(messages, tokenizer)
print(f"Tokens: {result.tokens_before} -> {result.tokens_after}")

Getting Help

Enable debug logging and check the output
Use simulate() to see what transforms would apply
Run validate_setup() for configuration issues
File an issue at github.com/headroom-sdk/headroom with your Headroom version, Python version, provider, debug log output, and minimal reproduction code

On this page