> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cockroach debug ballast

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](https://docs.cockroachlabs.com/docs/v24.2/cluster-setup-troubleshooting#automatic-ballast-files).

The `cockroach debug ballast` [command](https://docs.cockroachlabs.com/docs/v24.2/cockroach-commands) 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](https://docs.cockroachlabs.com/docs/v24.2/monitoring-and-alerting#node-is-running-low-on-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`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-zip), [`encryption-active-key`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-encryption-active-key), [`merge-logs`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-merge-logs), [`list-files`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-list-files), [`tsdump`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-tsdump), and [`ballast`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-encryption-decrypt) and [`job-trace`](https://docs.cockroachlabs.com/docs/v24.2/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](https://docs.cockroachlabs.com/docs/v24.2/support-resources).

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:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug ballast [path to ballast file] [flags]
```

View help:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug ballast --help
```

## Flags

| Flag | Description |
| - | - |
| `--size` `-z` | The amount of space to fill, or to leave available, in a node's storage directory via a ballast file. Positive values equal the size of the ballast file. Negative values equal the amount of space to leave after creating the ballast file. This can be a percentage (notated as a decimal or with %) or any bytes-based unit, for example: `--size=1000000000 ----> 1000000000 bytes` `--size=1GiB ----> 1073741824 bytes` `--size=5% ----> 5% of available space` `--size=0.05 ----> 5% of available space` `--size=.05 ----> 5% of available space` **Default:** `1GB` |

## Examples

### Create a 1GB ballast file (default)

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug ballast cockroach-data/ballast.txt
```

### Create a ballast file of a different size

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach debug ballast cockroach-data/ballast.txt --size=2GB
```

## See also

* [`cockroach` Commands Overview](https://docs.cockroachlabs.com/docs/v24.2/cockroach-commands)
* [Troubleshooting Overview](https://docs.cockroachlabs.com/docs/v24.2/troubleshooting-overview)
* [Production Checklist](https://docs.cockroachlabs.com/docs/v24.2/recommended-production-settings)