Troubleshooting

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.

Problem: Python SDK methods failing silently or returning None unexpectedly

Causes:

The Galileo SDK catches exceptions internally to prevent crashing your application
Errors are logged to a specific Python logger (galileo.utils.catch_log) that may not be configured in your application

Solutions:

Configure Python logging to see Galileo SDK errors by adding the following to your application code before importing Galileo:

import logging

# Configure the Galileo SDK logger
galileo_catch_logger = logging.getLogger('galileo.utils.catch_log')
galileo_catch_logger.setLevel(logging.WARNING)
galileo_catch_logger.addHandler(logging.StreamHandler())

# Now import and use Galileo
from galileo import GalileoLogger

Common silent failures include:
- Passing invalid parameters to SDK methods (e.g., unsupported keyword arguments)
- Network connectivity issues with Galileo APIs

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

LLM-as-a-judge metrics ask the judge model for a JSON response that holds the score. This error (code 1004) means the response wasn’t valid JSON or didn’t include a usable score. The metric shows an error for that metric value. Causes:

The judge model’s integration doesn’t enforce structured output. The model can then return malformed JSON, or add text around the JSON.
The model returned JSON, but not in the shape the metric expects.
Custom integrations don’t enforce structured output unless you turn on JSON schema support for the model.

Integrations that enforce structured output rarely hit this error. Galileo turns on structured output for these integrations with no setup on your side:

OpenAI
Azure OpenAI
Gemini Enterprise (formerly Vertex AI)
Anthropic: Claude Haiku 4.5, Sonnet 4.5 and later, and Opus 4.5 and later
AWS Bedrock: Claude Haiku 4.5, Sonnet 4.5, Sonnet 4.6, Opus 4.5 and Opus 4.6

Solutions:

Recompute the metric. A one-off malformed response may succeed on a second try.
If it keeps failing and you use a custom integration, turn on JSON schema support for this model in the integration settings.
Otherwise, use a judge model whose integration enforces structured output, such as one from the list above.

Judge responses cut off before they finish

Error code 1028 means the judge model reached its output limit before it finished the response, so the metric couldn’t be scored. Long step-by-step reasoning is a common cause. Solutions:

Switch to a less verbose judge model.
Turn off step-by-step reasoning in the metric’s settings, or ask for a concise rationale in the metric’s prompt.
You can’t change these settings on a preset metric. Duplicate the preset metric first, then change the copy.

Galileo Console UI

Problem: Console UI not loading

Causes:

Browser extensions are interfering with Galileo Console
Browser cache and cookies are interfering with Galileo Console

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...

// Example: GalileoLogger is used to assign Project Name and Log Stream name
import { GalileoLogger } from "galileo";
const logger = new GalileoLogger({
  projectName: "Your Project Name",
  logStreamName: "Your Log Stream Name"
});

// Example: galileoContext is used to assign Project Name and Log Stream name
import { galileoContext } from "galileo";

await galileoContext.init(
  {
    projectName: "Your Project Name",
    logstream: "Your Log Stream Name",
  }
);

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"}
)

// Import and initialize GalileoLogger
import { GalileoLogger } from "galileo";
const logger = new GalileoLogger({
  projectName: "Your Project Name",
  logStreamName: "Your Log Stream Name"
});

// Initialize a new trace and start listening for logs to add to it
const trace = logger.startTrace({
  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()

// Conclude and flush the logger to close to push captured logs
logger.conclude({ output: "Final output of experiment" })
await 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.add_workflow_span(
    input="Processing workflow",
    name="Main Workflow",
    metadata={ "workflow_type": "test" },
    tags=["workflow"])

import { GalileoLogger } from "galileo";
const logger = new GalileoLogger();

// Initialize a new trace
const trace = await logger.startTrace({
  input: "Your prompt",
  name: "Example Trace Name",
  tags: ["example_tag1", "example_tag2"],
  metadata: { example_key: "example_value" },
});

// Create a workflow span (parent span)
const 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",
                 duration_ns=3000000000)
logger.flush()

import { GalileoLogger } from "galileo";
const logger = new GalileoLogger();

// Initialize a new trace and start listening for logs to add to it
const trace = logger.startTrace({
  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:

Explore our Common Errors Guide and FAQ page.
Visit our Error Catalog.
Contact Support.

Overview

Get Started

Observability

Evaluation Metrics

Signals

AI Assistant

Luna Studio

Experiments

Agent Control

Annotations

Integrations

Security

References

Troubleshooting

SDK setup and configuration

Problem: SDK fails to initialize

Problem: Python SDK methods failing silently or returning None unexpectedly

API connectivity and authentication

Problem: 401 unauthorized when calling Galileo APIs

Problem: API requests timing out

Integration issues

Problem: Rate limit issues

Problem: JSON parsing errors

Judge responses cut off before they finish

Galileo Console UI

Problem: Console UI not loading

Problem: Logging data not appearing in Console UI

Problem: Spans appearing as separate traces

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

​SDK setup and configuration

​Problem: SDK fails to initialize

​Problem: Python SDK methods failing silently or returning None unexpectedly

​API connectivity and authentication

​Problem: 401 unauthorized when calling Galileo APIs

​Problem: API requests timing out

​Integration issues

​Problem: Rate limit issues

​Problem: JSON parsing errors

​Judge responses cut off before they finish

​Galileo Console UI

​Problem: Console UI not loading

​Problem: Logging data not appearing in Console UI

​Problem: Spans appearing as separate traces

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

SDK setup and configuration

Problem: SDK fails to initialize

Problem: Python SDK methods failing silently or returning None unexpectedly

API connectivity and authentication

Problem: 401 unauthorized when calling Galileo APIs

Problem: API requests timing out

Integration issues

Problem: Rate limit issues

Problem: JSON parsing errors

Judge responses cut off before they finish

Galileo Console UI

Problem: Console UI not loading

Problem: Logging data not appearing in Console UI

Problem: Spans appearing as separate traces

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