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.

In this reference:

Common connection errors

The following errors are applicable to all database integrations:

I/O error 

An I/O error occurred while sending to the backend.
Applicable to

PostgreSQL-backed database integrations
Level Critical
Category

Communication
Potential cause(s)

A transient communication error with the database occurred.
Suggested action(s)

If this error persists, refer to these troubleshooting tips to diagnose and treat the issue.

Back to Common error list
Back to top

Connection refused 

Connection refused. Check that the hostname and port are correct and that the postmaster is accepting TCP/IP connections.
Applicable to

All database integrations
Level Critical
Category

Communication
Potential cause(s)

Stitch is unable to connect to the database. This is typically a result of incorrectly entering connection details into Stitch, or a failure to whitelist Stitch’s IP addresses.
Suggested action(s)
  • Verify that the hostname entered in the Integration Settings page is correct.
  • Verify that the port entered in the Integration Settings page is correct.

  • Verify that Stitch’s IP addresses are whitelisted.

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

Back to Common error list
Back to top

Connection timeout 

Connection timed out.
Applicable to

All database integrations
Level Critical
Category

Communication
Potential cause(s)

The connection to the database timed out before Stitch could successfully establish a connection.
Suggested action(s)

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

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

Back to Common error list
Back to top

Unable to list databases and tables 

Could not list databases/tables for connection.
Applicable to

All database integrations
Level Critical
Category

Database user privileges
Potential cause(s)

Stitch is unable to access the databases or tables in your database, likely due to insufficient database user privileges.
Suggested action(s)

Verify that the database user authorizing the integration has the necessary privileges for the type of database you’re connecting.

Back to Common error list
Back to top

Incorrect password for database user 

FATAL: Password authentication failed for user [user_name]
Applicable to

All database integrations
Level Critical
Category

User credentials
Potential cause(s)

The credentials for the database user authorizing the connection are incorrect.
Suggested action(s)

Verify that the password entered into the Integration Settings page for the authorizing user is correct.

Back to Common error list
Back to top

Database type mismatch 

We encountered an error while attempting to check the type or version for this database. Please select the correct database type and try again.
Applicable to

All database integrations
Level Critical
Category

Incorrect Stitch setup
Potential cause(s)

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

For example: You select Microsoft SQL Server in Stitch, but we detect that it’s actually a Microsoft Azure SQL database.
Suggested action(s)

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.

Back to Common error list
Back to top

Internal error 

We encountered an internal error while checking the connection.
Applicable to

All database integrations
Level Critical
Category

Internal
Potential cause(s)

Stitch encountered an internal issue.
Suggested action(s)

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

Back to Common error list
Back to top

Unsupported table 

[table_name] unsupported
Applicable to

All database integrations
Level Critical
Category

Database user privileges or unsupported table format
Potential cause(s)
  • Stitch is unable to access the table, or
  • The table is in an unsupported format
Suggested action(s)
  • Verify that the database user authorizing the integration has the necessary privileges for the type of database you connected
  • Verify that the table is in a supported format for the type of database you connected

Back to Common error list
Back to top

MongoDB connection errors

Incorrect SSL configuration 

Prematurely reached end of file/stream
Applicable to

MongoDB database integrations
Level Critical
Category

SSL configuration
Potential cause(s)

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.
Suggested action(s)

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.

Back to MongoDB error list
Back to top

User database authentication mismatch 

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" }}}]
Applicable to

MongoDB database integrations
Level Critical
Category

Database setup
Potential cause(s)

This error usually means that the database entered into the Authentication Database field of the Integration Settings page is not the same database that’s used for user authentication.

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

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.
Suggested action(s)

  1. 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.

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

  2. 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.

  3. When finished, save the integration.

Back to MongoDB error list
Back to top

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.