Stitch periodically performs checks on the connection to your database to ensure the connection remains active and healthy. Below are some of the most common errors you might see if Stitch has trouble performing the connection check to your database and how to resolve them.


Common Errors

Meaning

Stitch is unable to access the databases or tables in your database.

Troubleshooting

Verify that the Stitch database user has the necessary permissions for the type of database you’re connecting.

You can find the permissions in the Creating a Stitch Database User section of the setup guide for your database.

Meaning

Stitch is unable to access the table or the table is in an unsupported format.

Troubleshooting

Verify that the Stitch database user has the necessary permissions for the type of database you’re connecting.

You can find the permissions in the Creating a Stitch Database User section of the setup guide for your database.

Meaning

Applicable only to MongoDB integrations, this error usually means that SSL has been incorrectly configured.

Connecting a database integration to Stitch via SSL has two parts: configuration on the database’s server and in the Stitch app. For the connection to be successful, the settings in both Stitch and on the database server must align.

For example: a MongoDB server doesn’t support SSL connections but the SSL option is checked in Stitch. This will result in a connection error.

Troubleshooting

First, verify if the MongoDB server is configured to support SSL connections. Then:

  • If SSL connections aren’t supported, make sure the Connect using SSL box in Stitch is unchecked and try saving the integration again.

  • If SSL connections are required, make sure the Connect using SSL box in Stitch is checked and try saving the integration again.

Full Message

In general, the error surfaced in Stitch will be similar to:

Timed out after XXXX ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}.

Client view of cluster state is {type=UNKNOWN, servers=[{address=[host]:[port], type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSecurityException:

Exception authenticating MongoCredential{mechanism=null, userName='[user_name]', source='[database_name]', password=, mechanismProperties={}}}, caused by {com.mongodb.MongoCommandException

Command failed with error 18: 'Authentication failed.' on server [[host]:[port].

The full response is { "ok" : 0.0, "errmsg" : "Authentication failed.", "code" : 18, "codeName" : "AuthenticationFailed" }}}]
Meaning

Applicable only to MongoDB integrations, this error usually means that the database entered into the Database field of the Integration Settings page is not the same database that’s used for user authentication.

Stitch requires a database user and a MongoDB server with auth enabled to create MongoDB connections. When authenticating a user in this way, MongoDB requires that the user be validated against their authentication database.

Currently, Stitch’s MongoDB integration currently assumes the database entered in the Integration Settings page is the authentication database. Due to MongoDB’s authentication process and Stitch’s current functionality, the database entered into Stitch must be the user’s authentication database.

Note: This database is only used to create the connection. Stitch will be able to detect any other databases the Stitch user has access to.

Troubleshooting
  • Ensure that the Stitch database user can perform all the required actions on the authentication database, in addition to any other databases that contain data you want to replicate. See the Create a Mongo Database user section of the Mongo setup guide for the full list of requirements.

    Note: If this is an Atlas-based MongoDB instance, the authentication database will be the admin database.

  • Once the Stitch user’s permissions have been verified, re-enter the name of the database into the Integration Settings page:

    • For Atlas-based MongoDB instances, this must be admin.
    • For other MongoDB instances, enter the name of the authentication database.
  • When finished, save the integration.

Meaning

Stitch encountered an error when attempting to ‘talk’ to your database.

Troubleshooting
  • Verify that the hostname entered in the Integration Settings page is correct.

    For Amazon-RDS: check that the port has been removed from the end of the hostname string.

  • Verify that the port setting entered in the Integration Settings page is correct.

  • Verify that Stitch’s IP addresses (see below) are whitelisted.

    For Amazon-RDS: Check that the Security Group and VPC Subnet associated with the database allows access from all Stitch’s IP addresses.

    • 52.23.137.21/32
    • 52.204.223.208/32
    • 52.204.228.32/32
    • 52.204.230.227/32
Meaning

The database type doesn’t match the database you selected in Stitch.

For example: you select MySQL in Stitch, but we detect that it’s actually a PostgreSQL database.

Troubleshooting

Verify that you’ve selected the correct database type. If the incorrect database type was chosen, select the correct database type and try completing the setup again.

Meaning

Something went wrong during the communication with the database.

Troubleshooting

This is a transient error and should clear itself during the next replication job. If this error persists, refer to these troubleshooting tips to diagnose and treat the issue.

Meaning

The credentials that Stitch has for your database are incorrect.

Troubleshooting

Verify that the correct password for the user Stitch is using to connect to the database is entered in the Integration Settings page of Stitch.

Meaning

The connection timed out before Stitch could successfully establish a connection.

Troubleshooting

This error may be transient and resolve on its own, but if it persists, try the following before contacting support:

  • Verify that the port setting entered in the Integration Settings page is correct.

  • Verify that Stitch’s IP addresses (see below) are whitelisted.

    For Amazon-RDS: Check that the Security Group and VPC Subnet associated with the database allows access from all Stitch’s IP addresses.

    • 52.23.137.21/32
    • 52.204.223.208/32
    • 52.204.228.32/32
    • 52.204.230.227/32
Meaning

Stitch encountered an internal issue.

Troubleshooting

This error is usually transient and will resolve on its own, but if it persists, please check our Status Page for reported service outages.


Check Stitch’s Status

If the troubleshooting steps detailed above don’t resolve the issue or if the errors persist, we recommend checking Stitch’s Status Page for reported service issues.


Contact Support

If there’s no reported service issue on our Status Page or you don’t see the error you’re receiving here, please get in touch with us.

To help us troubleshoot the problem quickly, we ask that you provide us with the following:

  1. The exact error you’re receiving. Providing us with the text or a screenshot is ideal.
  2. The type of database. Ex: MySQL.
  3. The display name of the database integration. This is the name of the integration as it appears on your Stitch dashboard page.
  4. Verification that Stitch’s IP addresses are whitelisted.
  5. Verification that the Stitch database user has the correct permissions for the type of database you’re connecting.

Questions? Feedback?

Did this article help? If you have questions or feedback, feel free to submit a pull request with your suggestions, open an issue on GitHub, or reach out to us.