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: