Error Reference

Both

Exception types, common errors, and troubleshooting guidance.

Traccia defines a hierarchy of exception types for different failure modes. This page documents all exception classes and common error scenarios.

Exception Hierarchy

All Traccia exceptions inherit from TracciaError:

TracciaError (base)
ConfigError
ValidationError
ExportError
RateLimitError
InitializationError
InstrumentationError

Exception Classes

TracciaError

Base exception class for all Traccia SDK errors.

python
class TracciaError(Exception):
    def __init__(self, message: str, details: dict = None)
    
# All Traccia exceptions include:
# - message: Human-readable error message
# - details: Optional dict with additional context

ConfigError

Raised when configuration is invalid or conflicting.

Common causes:

  • Missing required fields (e.g., api_key when using Traccia platform; endpoint is optional and defaults to the platform)
  • Invalid config file syntax (malformed TOML)
  • Conflicting options (multiple exporters enabled)
  • Invalid value types or ranges

Solution:

Run traccia doctor to diagnose configuration issues.

ValidationError

Raised when Pydantic validation fails (typically configuration validation).

Common causes:

  • sample_rate outside 0.0-1.0 range
  • Negative values for positive-only fields
  • Multiple exporters enabled simultaneously

Example:

python
from traccia.errors import ValidationError


try:
    init(sample_rate=1.5)  # Invalid: > 1.0
except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Details: {e.details}")

ExportError

Raised when span export fails (network issues, backend errors, etc.).

Common causes:

  • Endpoint unreachable or down
  • Invalid API key or authentication failure
  • Network timeouts
  • Backend rejecting payloads

Solution:

Run traccia check to test connectivity. Enable debug logging to see detailed error messages.

RateLimitError

Raised when rate limit is exceeded (in strict mode).

Common causes:

  • Span creation rate exceeds max_spans_per_second
  • Queue is full and max_block_ms exceeded

Solution:

Increase max_spans_per_second or max_queue_size, or reduce span creation rate with sampling.

InitializationError

Raised when SDK initialization fails.

Common causes:

  • Invalid exporter configuration
  • Missing required dependencies
  • Calling init() multiple times with conflicting configs

Solution:

Call stop_tracing() before re-initializing, or ensure dependencies are installed.

InstrumentationError

Raised when instrumentation or patching fails.

Common causes:

  • Library not installed (e.g., trying to patch OpenAI when not installed)
  • Incompatible library versions
  • Patching already-patched libraries

Solution:

Set enable_patching=False and use manual instrumentation, or install the missing library.

Common Error Scenarios

"No exporter is enabled! Traces won't be exported anywhere."

This happens when use_otlp=false but no other exporter is enabled.

Solution:

python
# Enable at least one exporter
init(enable_console_exporter=True)
# Or
init(enable_file_exporter=True)
# Or
init(use_otlp=True, endpoint="http://localhost:4318/v1/traces")

"OTLP exporter is enabled but no endpoint is configured"

OTLP requires an endpoint URL to send traces to.

Solution:

python
# Set endpoint
init(endpoint="http://localhost:4318/v1/traces")


# Or via environment variable
export TRACCIA_ENDPOINT="http://localhost:4318/v1/traces"

"Connection failed" or "Endpoint unreachable"

The SDK can't reach the configured endpoint.

Solution:

  1. Verify the endpoint is running: curl http://localhost:4318/v1/traces
  2. Check firewall and network settings
  3. Test connectivity: traccia check
  4. Try console exporter to verify SDK works: init(enable_console_exporter=True)

"ModuleNotFoundError: No module named 'tiktoken'"

Token counting requires the tiktoken library.

Solution:

bash
# tiktoken is a required dependency and should be auto-installed
pip install tiktoken


# Or disable token counting
init(enable_token_counting=False)

"No traces appearing in backend"

Traces are created but not showing up in Jaeger/Grafana/Platform.

Solution:

  1. Verify endpoint configuration: traccia doctor
  2. Check sample_rate isn't too low (try 1.0 for testing)
  3. Test with console exporter to verify spans are created
  4. Check backend logs for ingestion errors
  5. Ensure auto_start_trace is enabled (default)

Debugging Tips

Enable Debug Logging

python
from traccia import init


init(debug=True)


# Or via environment variable
export TRACCIA_DEBUG=true

Debug mode enables detailed logging of SDK operations, including span creation, export attempts, and error details.

Use Console Exporter for Testing

python
# Temporarily switch to console exporter
init(
    enable_console_exporter=True,
    debug=True
)


# Run your agent and check terminal output

Console exporter prints spans to stdout, helping you verify that instrumentation is working before troubleshooting backend connectivity.

Enable Span Logging

python
init(
    debug=True,
    enable_span_logging=True
)


# Logs every span start/end

Span logging provides visibility into the span processor pipeline, showing when spans are created, processed, and exported.

Use File Exporter for Analysis

python
init(
    enable_file_exporter=True,
    file_exporter_path="traces.jsonl"
)


# After running, inspect the file
cat traces.jsonl | jq

The file exporter writes spans to a JSONL file, allowing offline inspection and debugging without network dependencies.

Getting Help

GitHub Issues

Report bugs and request features

FAQ

Common questions and answers

Next Steps

CLI Commands

Use traccia doctor and check for diagnostics

Configuration Guide

Learn about all configuration options

© 2026 Traccia.