Welcome to the Galileo troubleshooting guide. This guide addresses common issues users may encounter when working with the Galileo SDK, API, Console, and overall integration process.


SDK Setup and Configuration

Problem: SDK fails to initialize

Causes:

  • SDK is out of date or improperly installed
  • Environment variables are improperly configured

Solutions:

  • Confirm Galileo is installed and check its version:
    • Python: pip show galileo
    • TypeScript: npm list galileo
  • Reinstall the SDK:
    • Python: pip install galileo
    • TypeScript: npm install galileo
  • Double-check .env configuration, making sure that API keys are correct, the keys are named correctly, and loaded via tools like dotenv.

API Connectivity and Authentication

Problem: 401 Unauthorized when calling Galileo APIs

Causes:

  • API keys are out of date or entered incorrectly
  • Environment variables are improperly configured

Solutions:

  • Re-generate your API token from the Galileo Console
  • Double-check .env configuration, making sure that API keys are correct, the keys are named correctly, and loaded via tools like dotenv.

Problem: API requests timing out

Causes:

  • Internet connectivity issues
  • Payload size in request exceeds limits

Solutions:

  • Ping Galileo endpoints to check latency using ping api.galileo.ai or curl -I https://api.galileo.ai.
  • Validate your internet connection by visiting other websites or performing a speed test.
  • Retry using a minimal payload by simplifying your API request body to the required fields only.
  • Verify you’re not exceeding rate limits by checking error response headers for limits.
  • Consider implementing exponential backoff for retry logic, using libraries like axios-retry or custom retry mechanisms.

Integration Issues

Problem: Rate limit issues

Causes:

  • Some metrics rely on OpenAI APIs or other external APIs which have their own rate limits
  • Some agents rely on external APIs which have their own rate limits

Solutions:

  • Request higher rate limits from OpenAI for your organization.
  • Use different API keys or organizations for separate projects or environments (e.g., production vs. pre-production) to distribute load.

Problem: JSON parsing errors

Causes:

  • Some metrics rely on OpenAI or other API responses being valid JSON

Solutions:

  • Retry the metric computation as transient errors may cause invalid JSON.
  • Check the output format of the model you’re using in its provider’s documentation, such as OpenAI’s.

Galileo Console UI

Problem: Console UI not loading

Causes:

Solutions:

  • Clear browser cache and reload by opening browser settings and selecting “Clear Cache and Site Data”.
  • Try accessing the Console in incognito mode to rule out extension or cookie conflicts.

Problem: Logging data not appearing in Console UI

Causes:

  • Incorrect Project name or Log Stream name
  • GalileoLogger or Traces not properly configured in application
  • Failing to conclude or flush the GalileoLogger

Solutions:

  • Confirm that the Project and Log Stream names in the UI match the names used when invoking the GalileoLogger or using galileo_context in your application code.

    ## Example: GalileoLogger is used to assign Project Name and Log Stream name
    from galileo import GalileoLogger
    logger = GalileoLogger(project="Your Project Name", log_stream="Your Log Stream Name")
    
    ## Example: galileo_context is used to assign Project Name and Log Stream name
    from galileo import galileo_context
    with galileo_context(project="Your Project Name", log_stream="Your Log Stream Name"):
        ## ...your AI application code...
    
  • In your application code, ensure the GalileoLogger is properly initialized and Traces are configured correctly.

    ## Import and initialize GalileoLogger
    from galileo import GalileoLogger
    logger = GalileoLogger(project="Your Project Name", log_stream="Your Log Stream Name")
    
    ## Initialize a new trace and start listening for logs to add to it
    trace = logger.start_trace(
        input="Your prompt",
        name="Example Trace Name"
        tags=["example_tag1", "example_tag2"],
        metadata={"example_key": "example_value"}
    )
    
  • At the end of your application code, ensure the GalileoLogger is concluded and logs are flushed.

    ## Conclude and flush the logger to close to push captured logs
    logger.conclude(output="Final output of experiment")
    logger.flush()
    

Problem: Spans appearing as separate Traces

Causes:

  • Spans not encapsulated within a Workflow Span
  • Traces invoked multiple times without concluding and flushing logs

Solutions:

  • Create a Workflow Span to act as a parent Span before logging other Spans.

    from galileo import GalileoLogger
    logger = GalileoLogger()
    
    ## Create a workflow span (parent span)
    workflowSpan = logger.addWorkflowSpan(
        input="Processing workflow",
        name="Main Workflow",
        metadata={ workflow_type: "test" },
        tags=["workflow"])
    
  • Ensure Traces are concluded and flushed after creating Spans, and look for loops in your application code that may invoke Traces multiple times.

    from galileo import GalileoLogger
    logger = GalileoLogger()
    
    ## Initialize a new trace and start listening for logs to add to it
    trace = logger.start_trace(
        input="Your prompt",
        name="Example Trace Name"
        tags=["example_tag1", "example_tag2"],
        metadata={"example_key": "example_value"}
    )
    
    ## ...Spans are created...
    
    ## Conclude the Trace and flush logs
    logger.conclude(output="Final trace output with all spans completed",
                     durationNs=3000000000)
    logger.flush()
    

Problem: Ground truth metrics are not appearing (e.g. BLEU, ROUGE)

Causes:

  • Dataset is missing an “output” column
  • No Ground Truths are provided

Solutions:

  • Check your experiment to confirm that your Dataset has an “output” column. If it does not, add one.
  • Metrics may appear to be missing because they do not apply to Log Streams. With Log Streams, no Ground Truths are provided.

For additional help: