Troubleshoot a database connection

Insights in ArcGIS Enterprise
Insights desktop

Database connections are supported in Insights in ArcGIS Enterprise and Insights desktop.

When creating a new database connection or trying to access an existing database connection, ArcGIS Insights may not be able to establish a connection to the database.

When a connection problem occurs, one of the following messages appears:

  • Invalid credentials. Ensure the username and password provided for this connection are correct indicates that an incorrect username or password was entered.
  • Invalid host. Ensure server name provided for this connection is valid and that the host is accessible indicates that an incorrect server name or port number was entered.
  • Invalid database name. Ensure database name provided for this connection is valid indicates that an incorrect database name or instance name was entered.
  • Insufficient privileges. Ensure the user has appropriate privileges on this database indicates that the database user requires additional privileges before a connection can be created between Insights and the database.
  • Something went wrong. Verify your connection properties, or click here to troubleshoot this is used for SAP HANA only. This error message indicates that one of the required parameters is incorrect.
  • Required library was not found. Ensure the database installation contains the required library. Click here for more information is used when an Oracle or PostgreSQL database is missing a required library. For Oracle, the required library is st_shapelib.dll on Windows or on Linux or Unix. For PostgreSQL, the required library is st_geometry.dll on Windows or on Linux.
  • Data connection issue. Check if connection properties need updating and that all required vendor files are uploaded indicates that one or more of the database connection properties have changed (for example, if the Warehouse name is missing or incorrect in a connection to Snowflake), or the vendor file is missing. Contact your database administrator to determine which properties require updates, or your ArcGIS administrator to determine if the vendor file is missing or requires updates.
  • We couldn't connect to the database indicates that the error could not be identified. The most common cause of this error is invalid credentials for connections to Google BigQuery (Project or Private key) or Snowflake (Username, Password, or Warehouse name).
  • SSL certificate error. Refer to the help documentation for more information indicates that a certificate authority (CA) is missing from the operating system. This error can occur when using Insights desktop on macOS to connect to SAP HANA Cloud (Connect using SSL is selected) or Snowflake. For information on importing a CA to your operating system, see the macOS help documentation.
  • The required connector type is not available. Contact an ArcGIS administrator to add or update the connector indicates that the database cannot be accessed because the connector is out of date or was deleted. The ArcGIS administrator can resolve issues with an outdated connector by deleting the connector then readding it with the latest files.
  • The required JDBC drivers are missing. Contact your ArcGIS administrator to remove the connector and re-add it with the necessary JDBC drivers indicates that the JDBC driver files from a database connector were deleted from ArcGIS Server. A member of the organization with administrator privileges must remove the connector type that is causing the error, then re-add the connector with the required vendor files. The database connection will automatically begin using the new connector once it is added. For more information on adding and removing connectors, see Manage connector types.

The following list provides common causes of database connection problems that can be investigated:

  • The connection properties, such as Username, Password, and Port number are invalid. Verify that the connection properties for the database connection are correct. If changes are required for an existing database connection, you can edit these properties by updating the database connection.
  • You don't have the database privileges required to create the connection.
  • Database vendor files are not present or the connector was not added correctly. See Manage connector types for more information.
  • The vendor files are out of date or unsupported. If an unsupported vendor file is used, the database connection may be made successfully, but newer functionality in Insights cannot be used. For example, certain spatial analysis capabilities may run without completing. For information on the latest certified vendor files, see Required vendor files.
  • The database is not configured to accept connections. Some databases require additional configuration to allow remote clients to connect. For example, for Microsoft SQL Server databases, you must enable the server network protocol to accept connections over the network.
  • Connections have been blocked. Database administrators can prevent users from connecting to a database while they perform certain database maintenance tasks, such as backup and recovery, and upgrades.

If you're having trouble using a database connection that previously worked in Insights, you may need to update the connection. Deleting the database connection will render any dependent datasets inoperable. You should only delete a relational database connection when you are sure no datasets are dependent, or you purposefully want to disable upstream datasets.