Docs Menu
Docs Home
/
Languages
/
Go
/
Go Driver

Connection Troubleshooting

On this page

  • Connection Error
  • Check Connection String
  • Configure Firewall
  • Authentication Error
  • Check Connection String
  • Verify the Authentication Mechanism
  • Verify User Is in Authentication Database
  • Error Sending Message
  • Check Connection String
  • Verify the Authentication Mechanism
  • Verify User Is in Authentication Database
  • Configure Firewall
  • Check the Number of Connections
  • Timeout Error
  • Set Timeout Option
  • Check the Number of Connections

This page offers potential solutions to issues you might encounter when using the MongoDB Go Driver to connect to a MongoDB deployment.

Note

This page addresses only connection issues. If you encounter any other issues with MongoDB or the driver, visit the following resources:

  • The Frequently Asked Questions (FAQ) for the Go driver

  • The Issues & Help page, which has information about reporting bugs, contributing to the driver, and finding additional resources

  • The MongoDB Community Forums for questions, discussions, or general technical support

Connection Error

The following error message is a general message indicating that the driver cannot connect to a server on the specified hostname or port:

Error: couldn't connect to server 127.0.0.1:27017

The following sections describe methods that may help resolve the issue.

Check Connection String

Verify that the hostname and port number in the connection string are both accurate. In the sample error message, the hostname is 127.0.0.1 and the port is 27017. The default port value for a MongoDB instance is 27017, but you can configure MongoDB to communicate on another port.

Configure Firewall

Assuming that your MongoDB deployment uses the default port, verify that port 27017 is open in your firewall. If your deployment uses a different port, verify the correct port is open in your firewall.

Warning

Do not open a port in your firewall unless you are sure that it is the port used by your MongoDB instance.

Authentication Error

The Go driver can fail to connect to a MongoDB instance if the authorization is not configured correctly. In these cases, the driver raises an error message similar to one of the following messages:

Command failed with error 18 (AuthenticationFailed): 'Authentication
failed.' on server localhost:27017.
connection() error occurred during connection handshake: auth error:
sasl conversation error: unable to authenticate using mechanism
"SCRAM-SHA-256": (AuthenticationFailed) Authentication failed.

The following sections describe methods that may help resolve the issue.

Check Connection String

An invalid connection string is the most common cause of authentication issues when attempting to connect to MongoDB.

Tip

For more information about connection strings, see Connection URI in the Connection Guide.

If your connection string contains a username and password, ensure that they are in the correct format.

Note

If the username or password includes any of the following characters, they must be percent encoded:

: / ? # [ ] @

When connecting to a replica set, include all the replica set hosts in your connection string. Separate each of the hosts in the connection string with a comma. This enables the driver to establish a connection if one of the hosts is unreachable.

Verify the Authentication Mechanism

Ensure that your credentials and authentication mechanism are correct. You can store your authentication credentials in environment variables or you can pass them to the SetAuth() method.

To learn more about authentication, see the Authentication Mechanisms guide.

Verify User Is in Authentication Database

To successfully authenticate a connection by using a database username and password, the username must be defined in the authentication database. The default authentication database is the admin database. To use a different database for authentication, specify the authSource in the connection string. The following example instructs the driver to use users as the authentication database:

uri := "mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=users"
client := mongo.Connect(context.TODO(), uri)

Error Sending Message

When the driver fails to send a command after you make a request, it often displays the following general error message:

com.mongodb.MongoSocketWriteException: Exception sending message

The following sections describe methods that may help resolve the issue.

Check Connection String

Verify that the connection string in your app is accurate. For more information about verifying your connection string, see Connection Error and Authentication Error.

Verify the Authentication Mechanism

Make sure you are using the correct authentication mechanism and credentials. For more information about authentication errors, see Authentication Error.

Verify User Is in Authentication Database

Verify the user is in the correct authentication database. For more information about the authentication database, see Authentication Error.

Configure Firewall

The firewall must have an open port for communicating with the MongoDB instance. For more information about configuring the firewall, see Connection Error.

Check the Number of Connections

Each Client instance supports a maximum number of concurrent open connections in its connection pool. The configuration parameter maxPoolSize defines this value and is set to 100 by default. If there are already a number of open connections equal to maxPoolSize, the server waits until a connection becomes available. If this wait time exceeds the maxIdleTimeMS value, the driver responds with an error. For more information about how connection pooling works, see How Does Connection Pooling Work in the Go Driver? in the FAQ.

Timeout Error

Sometimes when you send a request through the driver to the server, the request times out. When this happens, you might receive an error message similar to the following message:

timed out while checking out a connection from connection pool: context canceled

If you receive this error, try the following methods to resolve the issue.

Set Timeout Option

The Client supports a single Timeout option that controls the amount of time a single operation can take to execute. You can set this value by using the SetTimeout() method or by specifying the timeoutMS option in your connection string.

The following example sets the single timeout value to 5 seconds using the connection string option:

uri := "mongodb://<db_username>:<db_password>@<hostname>:27017/?timeoutMS=5000"
client := mongo.Connect(context.TODO(), uri)

Check the Number of Connections

The number of connections to the server may exceed maxPoolSize. For more information about checking the number of connections, see Error Sending Message.

Back

FAQ

Next

Issues & Help