OpenLineage Integration Troubleshooting¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

This page provides troubleshooting guidance for common issues with OpenLineage integration, applicable to all systems sending OpenLineage events to Alation.

For Airflow-specific troubleshooting, see Troubleshoot Airflow OpenLineage Configuration.

Lineage is not Appearing in Catalog¶

Problem¶

OpenLineage events are being sent successfully (200 OK response), but lineage doesn’t appear in the Alation catalog.

Cause 1¶

Data sources are not cataloged in Alation. The input or output data sources referenced in the event don’t exist in Alation.

Solution 1¶

Navigate to the Sources page in Alation.
Verify that both input and output data sources are added to the catalog.
If missing, add the data sources through the appropriate connector.
Run metadata extraction on the data sources.

Cause 2¶

The namespace in the OpenLineage event doesn’t match the JDBC URI configured in the Alation data source.

Solution 2¶

Open the data source Settings page in Alation.
Compare the namespace from your OpenLineage event with the JDBC URI in the data source configuration
If they don’t match:
1. Update your OpenLineage events to use the correct namespace that matches Alation’s JDBC URI.
2. Configure Additional Datasource Connections in Alation to recognize alternative host and port combinations.
See Configure Cross-Source Lineage for more information on additional datasource connections.

Example:

OpenLineage event namespace: postgres://prod-db-alias.example.com:5432
Alation JDBC URI: jdbc:postgresql://prod-db.example.com:5432/sales_db
Since these don’t match, add prod-db-alias.example.com:5432 as an additional datasource connection.

Cause 3¶

Alation reads the host/port from the “name” field in the OpenLineage event. If your events structure this differently, lineage may not resolve.

Solution 3¶

Ensure your OpenLineage event’s dataset name field includes the full path: database.schema.table.
Verify the namespace contains the correct host and port.
If you have different requirements for how host/port should be extracted, contact Alation support.

Cause 4¶

The specific tables referenced in the OpenLineage event haven’t been extracted by Alation’s metadata extraction.

Solution 4¶

Navigate to the data source in Alation.
Run metadata extraction (MDE).
Verify the specific tables appear in the catalog after extraction.
If tables are excluded by filters, adjust extraction settings.

Cause 5¶

There may be a delay between event ingestion and lineage appearing in the UI.

Solution 5¶

Wait for a few minutes after sending an event.
Refresh the Lineage tab in the catalog
Check Alation system logs if delay persists beyond 15 minutes

Authentication Errors¶

Problem¶

Receiving 401 Unauthorized or 403 Forbidden responses when sending events.

Cause 1¶

Invalid or Expired API Token.

Solution 1¶

Verify the API token is valid and hasn’t expired.
Go to Settings > Server Admin > API Access Tokens and check the token expiration date in Alation.
Generate a new token if expired.
Update your integration configuration with the new token.

Cause 2¶

Incorrect authorization header format.

Solution 2¶

Ensure the Authorization header uses Bearer token format: Bearer <your-token>.
Verify there’s a space between “Bearer” and the token.
Check for extra spaces or newline characters in the token value.
Do not include quotes around the token.

Cause 3¶

Insufficient permissions.

Solution 3¶

Verify the API token was created by a Server Admin.
Ensure the token has appropriate permissions for the OpenLineage API endpoint.
Create a new token with correct permissions if needed.

Invalid Event Format Errors¶

Problem¶

Receiving 400 Bad Request responses when sending events.

Cause 1¶

Malformed JSON.

Solution 1¶

Validate JSON syntax using a JSON validator (jsonlint.com).
Check for missing commas, brackets, or quotes.
Ensure proper escaping of special characters.
Verify the Content-Type header is application/json.

Cause 2¶

Missing required fields.

Solution 2¶

Ensure your event includes all required fields:

eventType (string: COMPLETE)

eventTime (string: ISO 8601 timestamp)

run (object with runId)

job (object with namespace and name)

inputs (array of dataset objects - at least one required)

outputs (array of dataset objects - at least one required)

Cause 3¶

Invalid timestamp format.

Solution 3¶

Use ISO 8601 format: 2024-02-20T10:30:00.000Z.
Include timezone (Z for UTC or +HH:MM offset).
Verify format matches: YYYY-MM-DDTHH:MM:SS.sssZ.

Connection and Network Errors¶

Problem¶

Unable to reach Alation endpoint, connection timeouts, or network errors.

Cause 1¶

Firewall or network restrictions.

Solution 1¶

Verify outbound HTTPS (TCP port 443) is allowed from your system to Alation.
Check corporate firewall rules.
Ensure your system can resolve Alation’s domain name.
Test connectivity: curl -v https://<your-tenant>.alationcloud.com/.

Cause 2¶

Incorrect Endpoint URL.

Solution 2¶

Verify the endpoint URL format: https://<your-tenant>.alationcloud.com/open_lineage_event/.
Check for typos in the tenant name.
Ensure /open_lineage_event/ path is correct (note the trailing slash).

Debugging Steps¶

General Debugging Workflow¶

Follow this systematic approach to debug OpenLineage issues:

Verify if the event is being sent:
- Add logging to capture the full event payload before sending.
- Log the HTTP response code and body.
- Confirm the event is actually reaching your sending code.
Validate event structure:
- Copy the event JSON to a validator (jsonlint.com).
- Check against OpenLineage specification.
- Verify all required fields are present.
- Test with the minimal event example from Direct API Integration for OpenLineage Events.
Test with cURL:
- Send a test event using cURL to isolate issues.
- Verify authentication works independently.
- Confirm endpoint is reachable.
- Use -v flag for verbose output.
Check Alation configuration:
- Verify data sources are cataloged.
- Confirm metadata extraction has run.
- Check JDBC URIs match event namespaces.
- Review Additional Datasource Connections if configured.
Review event logs:
- Check your application logs for errors.
- Review Alation system logs (if you have access).
- Look for patterns in successful vs failed events.

Enable Detailed Logging¶

Python Example (requests library):

import requests
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

response = requests.post(
    url,
    headers=headers,
    json=event
)

print(f"Status: {response.status_code}")
print(f"Response: {response.text}")

cURL Example (verbose output):

curl -v -X POST 'https://your-tenant.alationcloud.com/open_lineage_event/' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d @event.json

Test with Minimal Event¶

Start with the simplest possible event to verify basic connectivity:

{
  "eventType": "COMPLETE",
  "eventTime": "2024-02-20T10:00:00.000Z",
  "run": {"runId": "test-001"},
  "job": {
    "namespace": "test-system",
    "name": "test-job"
  },
  "inputs": [
    {
      "namespace": "postgres://your-db-host:5432",
      "name": "db.schema.source_table"
    }
  ],
  "outputs": [
    {
      "namespace": "postgres://your-db-host:5432",
      "name": "db.schema.target_table"
    }
  ]
}

Replace your-db-host with an actual cataloged data source in Alation, and ensure the tables exist.

Limitations¶

The following are current limitations of the OpenLineage integration.

Only COMPLETE Events Create Lineage. OpenLineage events with eventType other than COMPLETE are rejected and do not create lineage.
Both inputs and outputs are required. Events must include at least one input dataset and at least one output dataset.
The Airflow icon indicator on lineage graphs only appears in Alation’s New User Experience.
The namespace field must be a valid URL-like format that can be parsed to extract database type, host, and port.
The name field should follow database.schema.table format for relational databases.

OpenLineage Integration Troubleshooting¶

Lineage is not Appearing in Catalog¶

Problem¶

Cause 1¶

Solution 1¶

Cause 2¶

Solution 2¶

Cause 3¶

Solution 3¶

Cause 4¶

Solution 4¶

Cause 5¶

Solution 5¶

Authentication Errors¶

Problem¶

Cause 1¶

Solution 1¶

Cause 2¶

Solution 2¶

Cause 3¶

Solution 3¶

Invalid Event Format Errors¶

Problem¶

Cause 1¶

Solution 1¶

Cause 2¶

Solution 2¶

Cause 3¶

Solution 3¶

Connection and Network Errors¶

Problem¶

Cause 1¶

Solution 1¶

Cause 2¶

Solution 2¶

Debugging Steps¶

General Debugging Workflow¶

Enable Detailed Logging¶

Test with Minimal Event¶

Limitations¶

Alation User Documentation PDFs