This troubleshooting guide is organized by categories denoted by the section headers (see this page's Table of Contents). This guide will cover common failure modes for the IDBS connector and steps that can be taken to identify the cause and resolve the issue.

To quickly locate a relevant part of the troubleshooting section, use the browser’s search capability (Ctrl+F or ⌘+F) and type part of the error message or code.

Category: Connector Configuration

HTTPS Not Enabled

When the connector is first started, HTTPS is not enabled because there is no certificate configured. If you try to access the connector at https://<connector-hostname>:<port>/, you will see the below message (ERR_SSL_PROTOCOL_ERROR). Change the URL to http://<connector-hostname>:<port>/ instead.

HTTPS Enabled

If the connector is configured with HTTPS enabled and you try to access the connector at http://<connector-hostname>:<port>/, you will see a message like below (ERR_EMPTY_RESPONSE). Change the URL to https://<connector-hostname>:<port>/ to use HTTPS.

Incorrect Hostname or Port

If you try to access the connector and receive a message like below (ERR_CONNECTION_REFUSED), check the hostname and port in the URL and verify that the connector is running (e.g. with docker container ls).

Invalid Certificate or Private Key

If an invalid certificate or private key is used, the certificate and private key do not match, or the certificate is expired, the save will fail and an informative error message will be displayed. This helps to prevent the connector from being configured to state which makes it impossible to start.

Category: Single Sign-On

🚧

Potential Unrecoverable State...

Incorrect Single Sign-On settings can lead to an unrecoverable state (e.g. admin user can’t log in to fix the configuration).

Before making any configuration changes in these areas, export the current configuration using the Export Configuration button in the Connector settings screen to easily revert back to a known-working state. The exported configuration will contain all connector settings and DataWeave scripts.

Single Sign-On Not Enabled

If you are expecting to log in to the connector using corporate credentials, but you get the standard connector login screen below, double-check the Single Sign-On settings page and confirm that the fields are all completed and the Use Single Sign-On checkbox is checked.

Incorrect Cognito Settings

If you are trying to sign in using corporate credentials, but receive the following screen after clicking the Login with corporate credentials button, there is a problem with the Cognito configuration.

Incorrect Role Mapping

If the role mapping is configured incorrectly, users will not have the expected permissions. This can lead to an unrecoverable state if an admin is not able to log back in to fix the configuration. To mitigate this risk, please try to log into the connector using a different browser or an incognito window before closing the configuration page.

Category: Tetra Data Platform Settings

🚧

Potential Unrecoverable State...

Incorrect Tetra Data Platform settings can lead to an unrecoverable state (e.g. admin user can’t log in to fix the configuration).

Before making any configuration changes in these areas, you can export the current configuration using the Export Configuration button in the Connector settings screen. The exported configuration will contain all non-sensitive connector settings and DataWeave scripts, and can be imported from the Connector settings screen after resetting the config database.

Incorrect Tetra Data Platform Domain or Subdomain

If the domain or subdomain for the Tetra Data Platform (TDP) is incorrect, any API calls to TDP will fail. This will generally be seen in the Query step with a message like below (getaddrinfo ENOTFOUND {hostname}). Correct the TDP domain and subdomain in the Tetra Data Platform settings to resolve the error.

📘

Pre TDP v3.3

For TDP versions before v3.3, leave the subdomain field blank.

Incorrect Organization

If the TDP organization is incorrect, API calls to the Tetra Data Platform will fail. This will generally be seen with a message like below (This user does not belong to the requested organization). Correct the TDP organization in the Tetra Data Platform settings to resolve the error.

Incorrect Service User Token

If the TDP service user token is incorrect, API calls to the Tetra Data Platform will fail. This will generally be seen with a message like below (Invalid token). Correct the TDP service user token in the Tetra Data Platform settings to resolve the error.

Category: IDBS E-WorkBook Settings

Incorrect Server URL

If the IDBS E-WorkBook server URL is incorrect, API calls to IDBS E-WorkBook will fail. This will be seen in the Login step with a message like below (getaddrinfo ENOTFOUND {hostname}). Correct the server URL in the IDBS E-WorkBook settings to resolve the error.

Incorrect IDBS OAuth Settings

If any of the IDBS E-WorkBook OAuth settings are incorrect, the authentication process with IDBS E-WorkBook will fail. This will be seen in the Login step with a message like below (Response code 401 (Unauthorized) or Response code 400 (Bad Request)). Correct the OAuth settings in the IDBS E-WorkBook settings page to resolve the error.

Category: DataWeave

Invalid DataWeave Template ID

If a spreadsheet action refers to a template ID that doesn’t exist in the connector, this will be seen before the Login step with a screen like below (The spreadsheet expects a DataWeave template with key {template-id}, but no match was found in the configuration database.). Correct the template ID in the spreadsheet action or import the spreadsheet into the connector to resolve the error.

DataWeave Syntax Error

If there is a syntax error in a DataWeave script, a message like below will be seen with the DataWeave executable output included. Correct the syntax error and re-run the spreadsheet action to resolve this issue.