Skip to main content
CockroachDB automatically creates an emergency ballast file at startup time. The cockroach debug ballast command is still available but deprecated. For more information about how automatic ballast file creation works, see automatic ballast files. The cockroach debug ballast command creates a large, unused file that you can place in a node’s storage directory. In the case that a node runs out of disk space and shuts down, you can delete the ballast file to free up enough space to be able to restart the node.
  • Do not run cockroach debug ballast with a unix root user. Doing so brings the risk of mistakenly affecting system directories or files.
  • cockroach debug ballast now refuses to overwrite the target ballast file if it already exists. This change is intended to prevent mistaken uses of the ballast command. Consider adding an rm command to scripts that integrate cockroach debug ballast, or provide a new file name every time and then remove the old file.
  • In addition to placing a ballast file in each node’s storage directory, it is important to actively monitor remaining disk space.
  • Ballast files may be created in many ways, including the standard dd command. cockroach debug ballast uses the fallocate system call when available, so it will be faster than dd.

​
Subcommands

While the cockroach debug command has a few subcommands, users are expected to use only the zip, encryption-active-key, merge-logs, list-files, tsdump, and ballast subcommands. We recommend using the encryption-decrypt and job-trace subcommands only when directed by the Cockroach Labs support team. The other debug subcommands are useful only to Cockroach Labs. Output of debug commands may contain sensitive or secret information.

​
Synopsis

Create a ballast file:
View help:

​
Flags

​
Examples

​
Create a 1GB ballast file (default)

​
Create a ballast file of a different size

​
See also