> ## 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](/docs/stable/cluster-setup-troubleshooting.md#automatic-ballast-files).

The `cockroach debug ballast` [command](/docs/stable/cockroach-commands.md) 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](/docs/stable/monitoring-and-alerting.md#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`](/docs/stable/cockroach-debug-zip), [`upload`](/docs/stable/cockroach-debug-upload), [`encryption-active-key`](/docs/stable/cockroach-debug-encryption-active-key), [`merge-logs`](/docs/stable/cockroach-debug-merge-logs), [`list-files`](/docs/stable/cockroach-debug-list-files), [`tsdump`](/docs/stable/cockroach-debug-tsdump), and [`ballast`](/docs/stable/cockroach-debug-ballast) subcommands.

We recommend using the [`encryption-decrypt`](/docs/stable/cockroach-debug-encryption-decrypt) and [`job-trace`](/docs/stable/cockroach-debug-job-trace) subcommands only when directed by the [Cockroach Labs support team](/docs/stable/support-resources.md).

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](/docs/stable/cockroach-commands)
* [Troubleshooting Overview](/docs/stable/troubleshooting-overview.md)
* [Production Checklist](/docs/stable/recommended-production-settings.md)