Troubleshooting & FAQs

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="...",
    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 `HH_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]"`
`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,
    api_endpoint="https://honeyhive.internal.company.com",  # or set HH_API_URL
    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.dp1.us.honeyhive.ai,.honeyhive.ai"

Timeout Handling

Connection Timeouts

Symptom: ConnectionError: Connection timed out Solutions:

Increase timeout:

HoneyHiveTracer.init(
    api_key=api_key,
    timeout=60  # Increase from default 30s (or set HH_EXPORT_TIMEOUT=60)
)

Use batched async export (default): By default (disable_batch=False), spans are exported asynchronously in a background thread. span.end() returns immediately and spans are sent in batches, so export latency does not block your application.

HoneyHiveTracer.init(
    api_key=api_key,
    # disable_batch=False is the default - async batched export
)

Disable batching for serverless:

HoneyHiveTracer.init(
    api_key=api_key,
    disable_batch=True  # Synchronous inline export - use for Lambda/serverless
)

Read Timeouts

Symptom: ReadTimeout error but data appears in dashboard This is usually not a problem - data is being logged. The default batched async export handles this gracefully since exports happen in the background. If you are using disable_batch=True (synchronous mode), you can increase the timeout:

HoneyHiveTracer.init(
    api_key=api_key,
    timeout=120  # Longer timeout for slow networks
)

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["HH_API_KEY"])

Requires: pip install tenacity

Debugging Specific Issues

No tracer initialization message and no data logged

Checklist:

Verify API key is set: echo $HH_API_KEY
Enable verbose mode: verbose=True
Confirm the API key is scoped to the project you expect in the HoneyHive UI
Check firewall/VPN allows outbound HTTPS to api.dp1.us.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)
Confirm the API key is valid for your HoneyHive project
Check key hasn’t expired

Session created but no spans inside

Solutions:

Update honeyhive package: pip install -U honeyhive
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:

Ensure disable_batch=False (default) so exports happen asynchronously in the background
Increase timeout value if using disable_batch=True

Data takes long time to appear

Solutions:

Call tracer.flush() at end of execution to drain the batch queue
For Jupyter/serverless, always flush at end
Reduce flush_interval for faster delivery (default is 5 seconds), or set the HH_FLUSH_INTERVAL env var

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]"
For specific integrations: pip install "honeyhive[openai]"
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

The default batched async export works for both serverless and notebooks, just call tracer.flush() before the execution context ends to drain any queued spans.

tracer = HoneyHiveTracer.init(api_key=api_key)

# ... your code ...

tracer.flush()  # Drain the batch queue before the process/cell ends

Large payloads (>100k tokens)

Large payloads work well with the default batched async export since the HTTP request happens in a background thread and doesn’t block your application. If you need to verify delivery, call tracer.flush() after the span completes.

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

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?

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?