HoneyHive Docs

This document lists common issues and their solutions. If your issue isn’t listed, reach out on our Discord support channel.

Enable verbose logging for detailed debug output:

HoneyHiveTracer.init(
    api_key="...",
    project="...",
    verbose=True  # Enable debug logging
)

Common Errors Reference

Error	Cause	Solution
`403 Forbidden`	Invalid API key or TRACELOOP_API_KEY conflict	Check API key; remove TRACELOOP_API_KEY env var
`401 Unauthorized`	Missing or expired API key	Verify HONEYHIVE_API_KEY is set correctly
`SSL Certificate Error`	Certificate validation failure	See SSL/Certificate Issues
`Connection Timeout`	Network issues or firewall	See Timeout Handling
`Read Timeout`	Large payload or slow connection	Data is still logged; consider batch settings
`No data in session`	Package version mismatch	Update honeyhive package to latest
`ImportError`	Missing dependencies	Run `pip install "honeyhive[all]>=1.0.0rc0"`
`Rate limit exceeded`	Too many requests	Implement retry logic with backoff
`Payload too large`	Request exceeds 5MB limit	Truncate large inputs/outputs
`Context not propagated`	Thread/async context issues	See Multithreading guide

SSL/Certificate Issues

Certificate Validation Failure

Symptom: SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] Solutions:

Use system certificates:

import os
import ssl
import certifi

# Use certifi's certificate bundle
os.environ["SSL_CERT_FILE"] = certifi.where()

HoneyHiveTracer.init(...)

Provide custom CA certificate:

import os

# If using corporate proxy with custom CA
os.environ["SSL_CERT_FILE"] = "/path/to/company-ca.pem"
os.environ["REQUESTS_CA_BUNDLE"] = "/path/to/company-ca.pem"

HoneyHiveTracer.init(...)

Disable verification (development only):

# ⚠️ NEVER USE IN PRODUCTION
import ssl
ssl._create_default_https_context = ssl._create_unverified_context

Self-Signed Certificate

For on-premise deployments:

HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    api_endpoint="https://honeyhive.internal.company.com",
    verify_ssl=True,
    ca_bundle="/etc/ssl/certs/company-ca.pem"
)

Proxy Configuration

HTTP/HTTPS Proxy

import os

# Set proxy environment variables
os.environ["HTTP_PROXY"] = "http://proxy.company.com:8080"
os.environ["HTTPS_PROXY"] = "http://proxy.company.com:8080"
os.environ["NO_PROXY"] = "localhost,127.0.0.1,.internal.company.com"

# Then initialize HoneyHive
HoneyHiveTracer.init(...)

Authenticated Proxy

# With username:password
os.environ["HTTPS_PROXY"] = "http://user:password@proxy.company.com:8080"

Proxy with Custom CA

os.environ["HTTPS_PROXY"] = "http://proxy.company.com:8080"
os.environ["REQUESTS_CA_BUNDLE"] = "/path/to/proxy-ca.pem"

Bypassing Proxy

# Bypass proxy for HoneyHive API
os.environ["NO_PROXY"] = "api.honeyhive.ai,.honeyhive.ai"

Timeout Handling

Connection Timeouts

Symptom: ConnectionError: Connection timed out Solutions:

Increase timeout:

HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    timeout=60  # Increase from default 30s
)

Use async export:

HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    async_export=True  # Don't block on sends
)

Disable batching for serverless:

HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    disable_batch=True  # Send immediately
)

Read Timeouts

Symptom: ReadTimeout error but data appears in dashboard This is usually not a problem - data is being logged. To suppress:

HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    disable_batch=True,  # Smaller payloads
    timeout=120  # Longer timeout
)

Retry on Failure

import os
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def init_with_retry():
    HoneyHiveTracer.init(
        api_key=os.environ["HONEYHIVE_API_KEY"],
        project="my-project"
    )

Requires: pip install tenacity

Debugging Specific Issues

No tracer initialization message and no data logged

Checklist:

Verify API key is set: echo $HONEYHIVE_API_KEY
Check project name matches exactly
Enable verbose mode: verbose=True
Check firewall/VPN allows outbound HTTPS to api.honeyhive.ai
Verify SSL certificate is valid

403 Forbidden error

Solutions:

Remove TRACELOOP_API_KEY from environment if present
Verify API key is correct (check for whitespace)
Ensure key has access to the specified project
Check key hasn’t expired

Session created but no spans inside

Solutions:

Update honeyhive package: pip install -U "honeyhive>=1.0.0rc0"
Check your provider package versions are up to date
Verify traced functions are being called
For async code, ensure proper context propagation
Check that your provider package versions match the SDK requirements

Read timeout error

Don’t worry - data is usually still logged. To reduce:

Set disable_batch=True for smaller payloads
Increase timeout value
Use async_export=True for non-blocking sends

Data takes long time to appear

Solutions:

Set disable_batch=True to send immediately
Call HoneyHiveTracer.flush() at end of execution
For Jupyter/serverless, always flush at end

SSL validation failure

Solutions:

Set SSL_CERT_FILE environment variable
For corporate proxy, use company’s CA certificate
Install certifi: pip install certifi
Contact us for SSL .pem file if needed

Import or ModuleNotFoundError

Solutions:

Install full package: pip install "honeyhive[all]>=1.0.0rc0"
For specific integrations: pip install "honeyhive[openai]>=1.0.0rc0"
Check Python version (3.11+ required)

Rate limit exceeded

Solutions:

Implement retry with exponential backoff
Reduce trace frequency with sampling
Contact support for higher limits (Enterprise)

Payload too large (>5MB)

Solutions:

Truncate large inputs/outputs before tracing
Use references (URLs) for large files
Don’t trace binary data directly

Context not propagated in threads

See Multithreading guide for proper context propagation patterns.

Traces mixed up between requests

Cause: Using session_start() in a web server, or not creating sessions per request. session_start() stores the session ID on the tracer instance, so concurrent requests overwrite each other’s session.Solution: Use create_session() (sync) or acreate_session() (async), which store the session ID in request-scoped OpenTelemetry baggage:

@app.middleware("http")
async def session_middleware(request, call_next):
    await tracer.acreate_session(session_name=f"request-{request.url.path}")
    return await call_next(request)

See Tracer Initialization: Web Servers for full patterns.

evaluate() is using the wrong tracer

Cause: A global HoneyHiveTracer.init() call conflicts with the per-datapoint tracers that evaluate() creates automatically.Solution: Remove the global tracer when using evaluate(). Don’t pass tracer= to @trace decorators on functions called by evaluate():

# Let evaluate() manage tracers
@trace(event_type="tool")  # No tracer parameter
def my_function(input):
    pass

See Tracer Initialization: Evaluation for details.

General Recommendations

Python

Serverless / Jupyter Notebooks

# Always flush at the end
HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    disable_batch=True  # Send immediately
)

# ... your code ...

HoneyHiveTracer.flush()  # Required for serverless

Large payloads (>100k tokens)

HoneyHiveTracer.init(
    api_key=api_key,
    project="my-project",
    disable_batch=True  # Avoid timeout on large batches
)

Async code

See Multithreading guide for async context propagation.

Fallback Solution

If all else fails:

Separate provider calls into dedicated functions
Use @trace decorator on those functions
This gives you manual control over what’s traced

Known Limitations

Limitation	Workaround
Colab notebooks not supported	Use manual instrumentation
Max request size: 5MB	Truncate large payloads
Max nesting depth: 5 levels	Flatten deeply nested structures
Rate limit: 1000 req/min	Use sampling; contact for Enterprise limits

Rate Limits

Resource	Default Limit	Enterprise
Requests per minute	1,000	Configurable
Max request size	5 MB	5 MB
Filter nesting depth	5 levels	5 levels

Enterprise-plan users can configure higher rate limits.

Still Need Help?

Discord Community

Get help from the community

Email Support

Contact our support team

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

Troubleshooting & FAQs

Common Errors Reference

SSL/Certificate Issues

Certificate Validation Failure

Self-Signed Certificate

Proxy Configuration

HTTP/HTTPS Proxy

Authenticated Proxy

Proxy with Custom CA

Bypassing Proxy

Timeout Handling

Connection Timeouts

Read Timeouts

Retry on Failure

Debugging Specific Issues

General Recommendations

Python

Fallback Solution

Known Limitations

Rate Limits

Still Need Help?

Discord Community

Email Support

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

​Common Errors Reference

​SSL/Certificate Issues

​Certificate Validation Failure

​Self-Signed Certificate

​Proxy Configuration

​HTTP/HTTPS Proxy

​Authenticated Proxy

​Proxy with Custom CA

​Bypassing Proxy

​Timeout Handling

​Connection Timeouts

​Read Timeouts

​Retry on Failure

​Debugging Specific Issues

​General Recommendations

​Python

​Fallback Solution

​Known Limitations

​Rate Limits

​Still Need Help?

Discord Community

Email Support

Common Errors Reference

SSL/Certificate Issues

Certificate Validation Failure

Self-Signed Certificate

Proxy Configuration

HTTP/HTTPS Proxy

Authenticated Proxy

Proxy with Custom CA

Bypassing Proxy

Timeout Handling

Connection Timeouts

Read Timeouts

Retry on Failure

Debugging Specific Issues

General Recommendations

Python

Fallback Solution

Known Limitations

Rate Limits

Still Need Help?