Skip to main content

Connection and authentication issues

Resolve common connection and authentication issues when integrating Matillion with Atlan.

SSL verification failed​

Error

SSL verification failed: Unable to verify SSL certificate

Cause​

The Matillion server uses an SSL certificate that isn't signed by a well-known public Certificate Authority (CA), or the provided CA certificate doesn't match the certificate chain.

Solution​

  1. Verify you pasted the CA certificate, not the server's leaf certificate.
  2. If there are intermediate CAs in the chain, include the full chain (root + intermediates concatenated together).
  3. Check the certificate hasn't expired: 
    openssl x509 -in ca-cert.pem -noout -dates
  4. If your network uses an SSL inspection proxy, you may need the proxy's CA certificate instead.
  5. Verify the certificate is in PEM format (Base64-encoded text wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- delimiters).

Certificate authority required​

Error

Connection failed: SSL certificate verification error

Cause​

Your Matillion server uses a self-signed or internal CA SSL certificate, but no CA certificate was provided in the connection configuration.

You need to provide a CA certificate only when your Matillion server uses an SSL certificate that isn't signed by a well-known public Certificate Authority (CA). This typically applies when:

  • Your Matillion server uses a self-signed certificate
  • Your organization has an internal/private CA that signs server certificates

If your Matillion server uses a certificate from a public CA (such as DigiCert or LetsEncrypt), the system trust store already includes the CA and you can leave the CA Certificate field empty.

Solution​

  1. Determine what certificate to paste:

    Paste the CA certificate, which is the certificate of the Certificate Authority that signed your Matillion server's SSL certificate. Don't paste the server's own certificate.

    Your setupWhat to paste
    Self-signed server certificateThe server certificate itself (since it's its own CA)
    Internal CA (single root CA)The root CA certificate
    Internal CA (root + intermediates)The full CA chain: root CA followed by any intermediate CAs, concatenated together

  2. Obtain the CA certificate from your IT or security team.

  3. Alternatively, retrieve the certificate chain from your server:

    openssl s_client -connect <matillion-host>:<port> -showcerts </dev/null 2>/dev/null

    The last certificate in the output is typically the root CA.

  4. Make sure the certificate is in PEM format (Base64-encoded text wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- delimiters).

  5. In the Atlan connection configuration, paste the CA certificate in the CA Certificate field.

For detailed formatting guidance, see Provide SSL certificates.

Invalid certificate format​

Error

Certificate error: Invalid certificate format

Cause​

The certificate provided is in binary (DER) format instead of PEM format, contains invalid characters, or includes content that shouldn't be in the certificate field.

Solution​

  1. Make sure the certificate is in PEM format:

    The certificate must be Base64-encoded text wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- delimiters. For example:

    -----BEGIN CERTIFICATE-----
    MIIDazCCAlOgAwIBAgIJAOqRDRz0BxIAMA0GCSqGSIb3DQEBCwUAMIGZMQswCQYD
    ...
    u1Q==
    -----END CERTIFICATE-----

  2. If you have a certificate chain, paste them all concatenated together (root + intermediates).

  3. If you have a DER format certificate, convert it to PEM:

    openssl x509 -inform der -in certificate.der -out certificate.pem

  4. Don't paste the following:

    • The server's leaf certificate - This isn't a CA certificate and can't be used to verify itself
    • Private keys - Never paste private key content (-----BEGIN PRIVATE KEY-----)
    • Binary/DER format certificates - The field only accepts PEM (Base64 text) format

For detailed formatting guidance, see Provide SSL certificates.

Authentication failed​

Error

Authentication failed: Invalid username or password

Cause​

The provided username or password is incorrect, or the user doesn't have the required permissions in Matillion.

Solution​

  1. Verify the username and password are correct.
  2. Test authentication directly in the Matillion web interface.
  3. Make sure the user account is active and not locked.
  4. Verify the user has the required permissions:
    • Read access to projects
    • Access to metadata APIs
  5. If using API tokens, verify the token is valid and not expired.

Connection timeout​

Error

Connection timeout: Unable to reach Matillion server

Cause​

Network connectivity issues between Atlan and your Matillion server, or the hostname is incorrect.

Solution​

  1. Verify the hostname is correct and accessible: 
    ping <matillion-host>
    telnet <matillion-host> <port>
  2. Check that the Matillion server is running and accepting connections.
  3. Verify network latency is acceptable (under 200ms).
  4. Make sure there are no firewall rules blocking the connection.
  5. If using a secure agent, verify it can reach the Matillion server.
  6. Confirm the SSL port (usually 443) or non-SSL port (usually 80) is correct.

Known limitations​

Error

Lineage incomplete: Missing end-to-end lineage

Cause​

The Matillion connector has limitations based on API capabilities and version compatibility.

Solution​

Atlan currently supports the following for Matillion:

  1. Lineage support:

    • Lineage for asset transformations for Matillion version 1.68 LTS
    • End-to-end lineage is currently not supported
    • Column-level lineage isn't supported due to limitations of the Matillion ETL Metadata API

  2. Task history:

    • Task history for Matillion components is calculated based on the last 7 days of metadata crawled from the Matillion APIs

For the latest feature support, check the Matillion connector documentation.

See also​

Need help​

If you need assistance after trying the steps, contact Atlan support: Submit a request.