Cockroach Start Local Cluster

Have a Database Problem? Speak with an Expert for Free
Get Started >>


The horizontal scalability of the CockroachSQL database system is just one of the beneficial features that assist developers with efficiently storing and managing information. Cockroach is flexible too because you can run it on a cloud–either public or private, a web server, local machine, or use it as a business cluster for creating apps. Two more advantages of Cockroach are that it returns super fast responses to queries and offers low latency on a consistent basis. Experiment with it yourself. To begin, use this tutorial to learn how perform the Cockroach start local cluster steps in the fastest way.


  • CockroachDB – Download the appropriate version for your server or OS.

NOTE: Alternatively, use Docker containers. Run nodes of a cluster CockroachDB.

  • Use the command below to verify your version of CockroachDB:
cockroach version
  • You should receive a Build Tag: v19.2.2 response or something similar to it. If you didn’t, continue to the following section to install CockroachDB.

Install CockroachDB

If for whatever reason, the command cockroach version fails to return a version response, install the binary package so that you can continue this Cockroach start local cluster tutorial.

  • For your Linux machine, use the command wget to get the binary:
wget -qO- | tar  xvz
  • When completed, use cd command to access the directory archive like this:
cd cockroach-v19.2.2
  • Finally, use the command make to finish the service CockroachDB binary source build process:
make build

Install CockroachDB on Mac OS X

  • For your macOS X machine, use the v19 Cockroach repository in Homebrew. Input the brew install command from the terminal window in the macOS X:
brew install cockroachdb/tap/cockroach
  • After the installation is complete, run a Cockroach start local cluster with the command cockroach start --insecure.

Screenshot of Cockroach start local cluster install cockroachdb macos

NOTE: If during your cluster starting attempt, you see a failed to start server error message, work around it with --host or --advertise-host. Pass the port and domain to either one of those options.

  • Another way to get the Cockroach start local cluster to run successfully is to do a binary download with cURL. Duplicate the binary by copying it to the directory /usr/local/bin after the download is done.

  • Check it by attempting to use a few commands for cockroach. A cockroach: command not found error message indicates that the service failed to install properly.

Initialize the CockroachDB cluster

  • Enable the service for the Cockroach start local cluster to happen automatically by initializing it with the flag --help command:
cockroach init --help

Screenshot of CockroachDB cluster version and init help

Initialize an insecure CockroachDB cluster

  • Here’s how to perform a CockroachDB multi-node initialization with the flag --host command:
cockroach init --insecure --host localhost:26257

NOTE: Before you use your server to run the Cockroach cluster on it, confirm that your port is configured to be the same as what your settings state and that your IP address and host matches what they should be as well. Port 26257 is the CockroachDB default, but it may differ based on your specific configuration installation settings.

Create a bridge network for the CockroachDB nodes

Make a Docker bridge network so that you’ll be able to have many Docker containers for each node in Cockroach.

  • The command network create constructs a Docker network that’s named cluster_network in this example:
docker network create -driver bridge cluster_network

NOTE: The code you used above includes the option for --driver (shortened to -d) that identifies it as a bridge network.

Troubleshooting Cockroach start local cluster

You’ll need to have SSL security certificates for your Cockroach nodes; otherwise, an exception might be raised. Specifically, you might receive the ERROR: cannot load certificates or cockroach ERROR: cannot dial server error message.

Override the default CockroachDB hostname

Pass the port and domain explicitly to the flag --advertise-host if you receive a --advertise-addr: lookup Macs-MacBook-Pro.local: no such host exception.

  • Fix the hostname error like this:
cockroach start --insecure --advertise-host localhost:26257

Cockroach start local cluster

  • Use the command cockroach start to begin the Cockroach start local cluster process on your OS localhost. The below example shows an insecure cluster being started:
cockroach start --insecure --listen-addr=localhost
  • Here’s how to use the flag --store option to run a CockroachDB cluster for a particular node:
cockroach START                     \

    --insecure                      \

    --listen-addr=localhost:26257   \

    --store=node_1                  \


Let’s look at the details about the Cockroach start local cluster code you just entered above:

  • It puts the cluster of Cockroach in the foreground of your machine’s terminal. But you can select the option --background to run the service in the background if you prefer.

Screenshot of Cockroach start local cluster in terminal

  • At a terminal window, you can stop the Cockroach cluster by depressing the CTRL+C keys.

CockroachDB start in secure mode

Check that you have your SSL security certificates to avoid raising the exception ERROR: cannot load certificates when you want to run a secure cluster.

Cockroach start with join

Starting Cockroach with v19.2, the flag --join is required to join more than one node on your CockroachDB cluster. Now, pass as parameters the addresses of every node you want to join to a cluster.

List the CockroachDB nodes

  • Use this command to return a complete node listing when you run a CockroachDB cluster insecure instance:
cockroach node ls --insecure

CockroachDB CLI

  • While the Cockroach start local cluster is actively running, get to the interface for the command line with cockroach sql like this:
cockroach sql --insecure

Use the flag --certs-dir to Cockroach start local cluster from the command line interface (CLI) with a secure connection. Exit with the SQL q command. It takes you back to the command prompt or window terminal of your OS.

Start CockroachDB in Docker

To begin a Cockroach start local cluster when using Docker containers with Cockroach nodes, input the command docker ps. It will return a list so that you can get IDs of the containers you’re running and get to them that way.

WARNING: At this time, running a cluster of CockroachDB in Docker or in another similar containerized environment may result in an unstable combination. According to Cockroach Labs, there are still a lot of bugs that must be fixed for it to work seamlessly. If you’re an expert, have at it, but be aware of the issues that you may have to workaround.

Use Docker Exec to start a CockroachDB cluster

  • Get into a Docker CockroachDB node container with this command docker exec:
docker exec -it {NODE_CONTAINER_ID} /bin/bash
  • For your UNIX-based OS, use the / (forward slash) key to run the file.

  • Next, as long as the executable cockroach file and the cluster share directories, use this command to Cockroach start local cluster:

./cockroach start --insecure
  • If CockroachDB CLI is currently running, invoke the command sql like this:
./cockroach sql --insecure

Initialize CockroachDB in Docker

  • Use the command below to initialize the container from the outside of it:
docker exec -it node1 ./cockroach init --insecure

Troubleshooting CockroachDB in Docker

  • To see more detailed error messages in the Cockroach log when you Cockroach start local cluster, use the option --logtostderr:
./cockroach start --logtostderr
  • Your result should look similar to this:
logging to directory /cockroach/cockroach-data/logs
  • Alternatively, look within the directory for the /logs and read the logs for the node’s bind-mounted volume.

Screenshot of the CockroachDB logs directory in finder window

CockroachDB could not cleanup temporary directories

You might see the below exception:

ERROR: could not cleanup temporary directories from record file:

could not lock temporary directory

Fix the above error by deleting the temporary directory.

*Use the command rm -rf, and then put the directory path and temporary directory’s name:

rm -rf /cockroach/cockroach-data/cockroach-temp1234


This concludes this tutorial about Cockroach start local cluster with or within a containerized environment. There are several ways to get the cluster to run. For example, you can start it in an insecure or secure mode. With secure mode, you’ll need to have your CockroachDB’s SSL security certificates. We also addressed how to tackle common troubleshooting error messages you may encounter. CockroachDB has several benefits for DBAs and developers. It’s flexibility in scaling and super-fast response times makes learning how to start a local cluster worthwhile.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.