Compose Database-as-a-Service Help and Documentation

Everything you need to know about Compose, Hosted or Enterprise, is here in our help system. Whether you run one database for your businesses' sole application or six different databases to support an entire corporation, we've got the information you need.

Debugging MongoDB Connections

How do I debug MongoDB connections?

Many people are using different types of servers and platform-as-a-service offerings to connect to Compose servers. Thus, this document will provide a generic debugging process for MongoDB connection problems:

  1. Checking access to the host and port
  2. Access to MongoDB
  3. Using Authentication
  4. Checking your language's MongoDB driver

It is important to differentiate the points of contact with your Compose database. The three primary points are:

Localhost (i.e. development machine)

A local computer used for development. These machines connect to Compose over the Internet. Connections over the Internet often result in higher latency and slower connection rates. Compose environments can exist in different physical locations on the Internet -- depending on your location relative to your deployment, latency and speed can be variable.

Application server or PaaS provider

This server runs the application code for production or staging environments. Customers use a diverse set of products, such as virtual servers on AWS, DigitalOcean, Rackspace, Softlayer, Joyent, or Linode (among many others) for their application hosts, or PaaS providers like Heroku, OpenShift, or EngineYard. As with localhost connectivity, the location of your application server or PaaS provider relative to your Compose deployment can influence performance between the application server(s) and your Compose deployment.

Application code and driver

This would refer to the code that's initiating connections to any database hosted at Compose. If you're having problems connecting to your database, but the network is blameless, the problem would usually reside in the code itself.

MongoDB drivers are built to handle MongoDB replica sets and shards with high availability and scalability. With MongoDB drivers, development is active and versions change quickly. Most issues can be resolved by updating to the latest version of the driver. Please ensure you are running the latest version of your language's driver, and the driver has been updated in the past 6 - 9 months (e.g. in active development). Without using the latest driver, Compose's support will most likely be unable to troubleshoot or support any problems that you may be experiencing.

If you are comfortable with these distinctions, please see the following debugging steps:

Checking access to host and port

To check your network's ability to connect to the database on a fundamental level, you'll want to use either the widely available nc tool or the telnet client. You'll also want to check for connectivity from both your development machine (localhost) and from an application server, comparing the results.

Using nc with the -vz options (for verbose output and only asking nc to scan for an open port, respectively), run the following:

shell> nc -vz host port

If you can successfully make a connection, you'll see a response similar to this:

shell> nc -vz host port
Connection to host port [tcp/*] succeeded!

If you cannot successfully make a connection, you'll see a response similar to this:

shell> nc -vz host port
nc: connect to host port (tcp) failed: Connection timed out

Using a telnet client, you'd have a similar experience. Here's a sample of a successful connection (Look for Escape character is '^]'. as a sign of success):

shell> telnet host port
Trying host...
Connected to host.
Escape character is '^]'.

And here's an example of an unsuccessful connection attempt using the telnet client:

shell> telnet host port
Trying host...
telnet: connect to address host: Operation timed out
telnet: Unable to connect to remote host

In the examples listed that use a generic host and port placeholder, you can replace them with the specific hostname and port number from your Connection String URL within the Compose UI. For example, if your MongoDB URL is:


...then your host and port can be made up from either of the two pairs of hosts listed making the host and port 10764 or host and port 10361. In this case, we'll test the former so we run:

bash> telnet 10764
Connected to
Escape character is '^]'.


And now using the nc tool:

bash> nc 10965 -vz
found 0 associations
found 1 connections:
     1:	flags=82<CONNECTED,PREFERRED>
	outif en0
	src port 53687
	dst port 10965
	rank info not available
	TCP aux info available

Connection to port 10965 [tcp/*] succeeded!

More success!

If you do not have access to the command line, you can also open your web browser and attempt to access your MongoDB members through the a similar URL to the one found in the Compose UI. For example, using the same hostname and port again, go to in your web browser. It's important to note that the URL will start with either http:// or https:// depending on if you created the deployment with SSL enabled.

If you can successfully connect over HTTP/HTTPS you'll see the following message in plain text in your browser:

It looks like you are trying to access MongoDB over HTTP on the native driver port.


If your tests fail from one host (perhaps your local development machine) but succeed on another host, then it's likely that you have a firewall on one host that's blocking connections. Or perhaps the firewall is elsewhere in your infrastructure (such as a corporate firewall, or an ISP block). Compose does not block network access to deployments, so we would not have firewalls in place stopping you from being able to connect.

If your tests fail regardless of the host that you're connecting from, check the following:

  • Double check the host:port in Compose on the Database's "Admin" page. Mistakes happen! Maybe the port number was mistyped.
  • You'll still want to check to see if there's a common firewall or network gateway that all hosts have in common that could be blocking traffic to Compose over the ports that you need.
    • If you're connected via public wifi, it's very common for all ports except 80 and 443 to be blocked. Please try on a different network.
  • Flush your DNS cache and check your local hosts file) for anything that would interfere with name resolution taking place on public DNS rather than locally away from authoritative servers.

Access to MongoDB

From your localhost and application server (if you have mongo installed), if you have SSL/TLS enabled on your deployment, run:

bash> mongo --ssl --sslAllowInvalidCertificates host:port/dbname
mongo> db.isMaster()

Or, if you do not have SSL/TLS enabled, just run:

bash> mongo host:port/dbname
mongo> db.isMaster()

Note, that dbname may be admin as this is the default database in Compose MongoDB deployments.


Where the server is functioning correctly, the command will print: "ismaster": true. The isMaster() command is accessible without authentication on MongoDB, and provides a good check to see if MongoDB is responding.

If successful, continue to Using Authentication.


If isMaster() fails, check the following:

  • Download and view logs in the Compose UI for error messages regarding connection failures.

Using authentication

In the Compose UI, reset your username and password for your database. Access the Compose web interface, navigate to your database, delete your current user, and re-add your user. After resetting your username / password, run the following:

bash> mongo host:port/dbname
mongo> db.auth("yourusername", "yourpassword")

Your MongoDB username / password is not your web Compose username / password, but a different username / password that is set on the database.


On success, you will see: 1 (yes, that's all you'll see!). On success, attempt to rerun or debug your application code.


An authentication failure responds with: { ok: 0.0, errmsg: "auth fails" }

  • Reset your username / password again, and retry authentication
  • Create a new, different another username / password, and retry authentication with new username / password
  • Confirm host:port in Compose UI against values used in testing - refer back to Checking access to the host and port

Checking your language's MongoDB driver

For debugging issues with drivers, ensure that the previous three categories of test – Checking access to the host and port, Access to MongoDB and Using Authentication – are being passed successfully. Drivers can only be successful when there is a working underlying connection and authentication.

When testing a driver, test with the simplest form of code and build on top of success. By doing this, you will understand the failure point.


A successful connection means you can interact with your database from your programming language.


Typically, when diagnosing any failures, we do the following:

  • Strip the code down to the essentials
  • If the driver has debugging or verbose modes, turn them on for better visibility
  • In the Compose UI, look at MongoDB log files for errors
  • Insert more error logging into the database to determine cause
  • Double check driver documentation and syntax against the driver version

Still not connecting?

Please consider walking through the steps again, or contact our

Debugging MongoDB Connections