Troubleshooting¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Core Connector Core connectors are included with all Alation platform tiers (subject to each tier’s connector limits) and are fully supported by Alation.

Refer to Troubleshoot OCF Connectors.

Refer to the following scenarios for help in troubleshooting common issues.

Test Connection Failure¶

Verify that the Looker Client ID, Client Secret, and API URL are provided correctly on the Settings page. In most cases the Looker Base URL will be different from the API URL.

If you experience issues when connecting Alation to Looker through the OCF connector, use the following checks and steps:

Ensure that the correct port numbers are used:
- Determine whether your Looker instance is configured to use 443, 19999, or a custom port.
- For most installations, 443 is the default and recommended port.
- Use port 19999 only if your Looker installation requires it.
Update Connector Configuration

Ensure the correct port is specified in the Looker OCF connector settings in Alation. If unsure, consult your Looker administrator for the correct port number.
Check Network Accessibility
- Verify that the port is open and reachable from the Alation environment.
- Review firewall rules, security groups, proxies, or load balancers that may block outgoing or incoming traffic on the chosen port.
Validate API Availability from Alation
- Test the Looker API availability using tools such as curl from the Alation infrastructure
- A valid response indicates that the Looker API is running and accessible.
- If the test fails, check for SSL/TLS interception, proxy issues, or DNS resolution problems.
Engage Looker Administrators if Needed
- If issues persist, involve your Looker administrator, network team, or cloud platform administrators to validate configuration and connectivity.

Limited Folders Shown in Alation¶

Check the user permissions in Looker. The user needs permissions to access all the folders.

Datasource Details are not Displayed in Alation¶

Check the user permissions in Looker. The user needs admin privileges. Without admin privileges datasource information cannot be extracted.

Datasource Column or Report Column Details are not Displayed in Alation¶

Check whether the models are published in Looker and they have content inside them. You can check whether the following API response contains an empty explores field, then columns will not show up, for example:

<Looker API URL>/api/3.1/lookml_models/<Model Name>

{
      "has_content": false,
      "label": "Crm",
      "name": "crm",
      "project_name": "crm",
      "unlimited_db_connections": false,
      "allowed_db_connection_names": [
          "mysql"
      ],
      "explores": [],
      "can": {
          "index": true,
          "show": true,
          "create": true,
          "update": true,
          "destroy": true
      }
}

Lineage is not Visible¶

If the lineage is not visible, make sure the datasource is cataloged in Alation and make sure the user has admin privileges.

Metadata Extraction Fails with API Endpoint Errors¶

Problem¶

You are running metadata extraction from the Metadata Extraction tab in your Looker OCF connector settings. During Metadata Extraction, after successful authentication, the extraction job fails.

The error appears in the Job History page for the metadata extraction job. You see one or more of the following symptoms:

HTTP 404 errors for API endpoints in the connector logs
Authentication succeeds but extraction job fails with “API endpoint not found” errors
Missing metadata for certain object types (folders, dashboards, explores, or reports)
Error messages such as: Error accessing API endpoint: /api/4.0/<endpoint> or API version not supported

As a result, you cannot extract metadata from Looker into Alation, or you receive incomplete metadata in your catalog.

Cause¶

This issue occurs when the Looker instance does not have API version 4.0 enabled or accessible. The Looker OCF connector uses API version 4.0 endpoints to extract metadata. If your Looker instance only has older API versions enabled (such as 3.1 or 3.0), the connector cannot access the required endpoints.

Additionally, API access might be restricted by permissions, network policies, or Looker configuration settings that prevent the connector service account from reaching API endpoints.

Solution¶

Follow these steps to resolve API endpoint errors:

Verify your Looker instance API version:
1. Access the following URL in your browser: <Looker URL>/api/versions
2. Confirm that version 4.0 appears in the list of available API versions
3. If version 4.0 is not listed, contact your Looker administrator to enable API version 4.0 on your Looker instance
Verify API access permissions for the connector service account:
1. Log in to Looker Admin console
2. Navigate to Admin > Users and locate the service account used by the connector
3. Click on the user and go to Roles
4. Ensure the role includes the following permissions:
  - access_data - Allows API access to data
  - see_lookml - Allows access to LookML models and explores
  - see_looks - Allows access to looks (reports)
  - see_user_dashboards - Allows access to dashboards
5. If any permissions are missing, add them to the role or assign a role that includes these permissions
Check API configuration in Looker:
1. In Looker Admin console, go to Admin > Platform > API
2. Verify API access is enabled
3. Check if API rate limiting is configured; if extraction jobs are timing out, request increased rate limits from your Looker administrator
4. If an IP whitelist is configured, ensure the Alation server IP address is whitelisted
Enable DEBUG logging in the connector:
1. In Alation, go to your Looker connector Settings page
2. Scroll to Logging Configuration and set Log Level to DEBUG
3. Save the settings
4. Run the metadata extraction test connection again
5. After the test completes, go to General Settings > View Logs to examine the detailed connector logs
6. Look for specific API errors indicating which endpoint failed
7. If the issue persists, collect the logs and contact Alation Support

Logs to be collected¶

Refer to Logs to be collected.

Table Names in BIDatasource Fields table¶

If you encounter issues related to table names in the BI Datasource Fields table, refer to Table Name in BI Datasource Fields Catalog Page.