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

# cockroach debug ballast

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

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 <InternalLink path="cluster-setup-troubleshooting#automatic-ballast-files">automatic ballast files</InternalLink>.

The `cockroach debug ballast` <InternalLink path="cockroach-commands">command</InternalLink> 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 <InternalLink path="monitoring-and-alerting#node-is-running-low-on-disk-space">monitor remaining disk space</InternalLink>.
* 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 <InternalLink path="cockroach-debug-zip">`zip`</InternalLink>, <InternalLink path="cockroach-debug-encryption-active-key">`encryption-active-key`</InternalLink>, <InternalLink path="cockroach-debug-merge-logs">`merge-logs`</InternalLink>, <InternalLink path="cockroach-debug-list-files">`list-files`</InternalLink>, <InternalLink path="cockroach-debug-tsdump">`tsdump`</InternalLink>, and <InternalLink path="cockroach-debug-ballast">`ballast`</InternalLink> subcommands.

We recommend using the <InternalLink path="cockroach-debug-encryption-decrypt">`encryption-decrypt`</InternalLink> and <InternalLink path="cockroach-debug-job-trace">`job-trace`</InternalLink> subcommands only when directed by the <InternalLink path="support-resources">Cockroach Labs support team</InternalLink>.

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`<br />`-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:<br /><br />`--size=1000000000 ----> 1000000000 bytes`<br />`--size=1GiB ----> 1073741824 bytes`<br />`--size=5% ----> 5% of available space`<br />`--size=0.05 ----> 5% of available space`<br />`--size=.05 ----> 5% of available space`<br /><br />**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

* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
* <InternalLink path="troubleshooting-overview">Troubleshooting Overview</InternalLink>
* <InternalLink path="recommended-production-settings">Production Checklist</InternalLink>