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.

For information about logs, refer to Troubleshoot OCF Connectors.

Proxy Configuration Error

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with the following error: Proxy configuration error. Ensure that the proxy URI and port are correct.

Cause

In the Proxy configuration section of the General Settings tab, you have selected the Use Proxy checkbox; however, the Proxy URI field is empty or invalid.

Solution

  1. Verify that the Proxy URI field contains a valid proxy server address in the format http(s)://hostname.

  2. Verify that the Proxy Port field contains a valid port number.

  3. Click Save and retry the connection test.

Proxy Authentication Failed

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with the following error: Proxy authentication failed. Verify the proxy URI, port, and credentials.

Cause

The proxy server rejected the authentication credentials. This can occur when:

  • The proxy username or password is incorrect.

  • For Kerberos proxy authentication, the domain/realm is incorrect or the KDC is unreachable.

  • The proxy server returned an HTTP 407 (Proxy Authentication Required) response.

Solution

  1. Verify the Proxy Username and Proxy Password fields.

  2. For Basic proxy authentication, confirm the credentials are valid by testing them independently against the proxy server.

  3. For Kerberos proxy authentication:

    • Verify the Proxy Kerberos Domain field contains the correct realm (for example, CORP.EXAMPLE.COM).

    • Ensure the KDC (Key Distribution Center) is reachable from the connector host.

    • If a custom krb5.conf is required, upload it in the Kerberos Config (krb5.conf) field.

Kerberos Login Failed

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with the following error: Proxy authentication failed. Verify proxy username, password, and domain/realm. For Kerberos, also ensure the KDC is reachable from the connector host.

Cause

The Kerberos kinit operation failed. The connector could not obtain a Ticket Granting Ticket (TGT) from the KDC.

Solution

  1. Verify the Proxy Username field contains the correct Kerberos principal name.

  2. Verify the Proxy Password is correct.

  3. Verify the Proxy Kerberos Domain matches the Kerberos realm configured on the KDC.

  4. Ensure the KDC is reachable from the connector host on the network. You can test this by running kinit manually on the host.

  5. If the KDC hostname differs from the proxy host, upload a custom krb5.conf file.

Missing Kerberos Username or Domain

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with one of the following errors: Kerberos proxy authentication requires a username or Kerberos proxy authentication requires a domain/realm.

Cause

The Proxy Authentication Type is set to Kerberos, but the required fields are empty.

Solution

  1. Enter the Kerberos principal name in the Proxy Username field.

  2. Enter the Kerberos realm in the Proxy Kerberos Domain field (for example, CORP.EXAMPLE.COM).

Proxy SSL Certificate Error

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with the following error: Failed to load proxy SSL certificate. Ensure the uploaded certificate is a valid X.509 PEM file.

Cause

The uploaded proxy SSL certificate could not be parsed. The file may not be a valid X.509 PEM certificate.

Solution

  1. Verify that the uploaded file is a valid X.509 certificate in PEM format (begins with -----BEGIN CERTIFICATE-----).

  2. Re-upload the certificate in the Proxy SSL Certificate field.

  3. If you are unsure about the certificate format, contact your network administrator to obtain the proxy’s root CA certificate in PEM format.

SSL Certificate Validation Failed

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with the following error: SSL certificate validation failed. If using a proxy with SSL inspection (MITM), upload the proxy’s CA certificate in the Proxy SSL Certificate field.

Cause

The HTTPS connection to Azure AD (login.microsoftonline.com) failed because the SSL certificate could not be validated. This typically occurs when:

  • A proxy with SSL inspection (MITM) is intercepting HTTPS traffic and re-signing it with its own CA certificate.

  • The proxy’s CA certificate is not trusted by the connector.

Solution

  1. Obtain the proxy server’s root CA certificate from your network administrator.

  2. Upload the certificate in the Proxy SSL Certificate field.

  3. Click Save and retry the connection test.

  4. If connecting directly (without a proxy), ensure the server’s SSL certificate is issued by a trusted CA.

Proxy Authentication Fails After Updating Credentials

Problem

After updating the proxy username, password, or authentication type on the General Settings tab, when you run the test connection, it fails with a proxy authentication error.

Cause

The JVM caches proxy credentials internally. When you update the proxy credentials or switch the authentication type (for example, from Basic to Kerberos), the cached credentials from the previous configuration may still be used, causing authentication to fail.

Solution

Restart the connector from the Manage Connectors page to clear the cached credentials, then retry the connection test.

Azure AD Authentication Failed Through Proxy

Problem

After configuring the connector settings on the General Settings tab, when you run the test connection, it fails with the following error: Azure AD authentication failed. Verify the Azure AD username and password.

Cause

The Azure AD token acquisition failed. When using a proxy, this can occur if:

  • The Azure AD username or password is incorrect.

  • The proxy is blocking HTTPS traffic to login.microsoftonline.com.

  • The proxy requires SSL inspection and the proxy CA certificate is not uploaded.

Solution

  1. Verify the Azure AD Username and Password in the Data Source Connection section.

  2. Ensure the proxy allows HTTPS traffic to login.microsoftonline.com and login.windows.net.

  3. If the proxy performs SSL inspection, upload the proxy’s CA certificate in the Proxy SSL Certificate field.

  4. Check the connector logs for detailed error messages.