# DBX CLI Error Codes: Complete Reference for Error Handling and Debugging

> Master DBX CLI error codes with this complete reference. Understand and resolve invalid arguments, connection issues, and more for efficient debugging.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: api-reference
- Published: 2026-07-10

---

**The DBX CLI returns seven distinct error codes—`INVALID_ARGUMENT`, `INVALID_OPTION`, `UNKNOWN_OPTION`, `CONNECTION_NOT_FOUND`, `DBX_NOT_RUNNING`, `USAGE`, and `ERROR`—each emitted by the `CliError` class in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts) to indicate specific failure modes ranging from invalid CLI arguments to missing Desktop bridge connections.**

The DBX command-line interface provides structured error reporting through well-defined exit codes that enable programmatic error handling. When commands fail, the CLI surfaces machine-readable error codes via the `CliError` class, allowing automation scripts to distinguish between configuration issues, connection problems, and usage errors. This guide examines the complete set of DBX CLI error codes defined in the t8y2/dbx repository, their specific triggers in the source code, and practical debugging strategies.

## How DBX CLI Error Handling Works

The DBX CLI implements centralized error handling through the `CliError` class defined in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts). When an exception occurs, the CLI catches the error, extracts the `code` property, and formats output as either plain text or JSON depending on the terminal environment.

The error formatting logic resides in [`packages/cli/src/cli-format.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli-format.ts), which constructs the JSON payload containing the `code` and `message` fields. This design ensures that calling processes can parse failures programmatically while maintaining human-readable output for interactive debugging.

## Complete List of DBX CLI Error Codes

The following error codes are thrown at specific locations within [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts) to indicate distinct failure conditions.

### INVALID_ARGUMENT

**Thrown at lines 164 and 284** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code indicates the command received an illegal combination of arguments or the wrong number of arguments. Common triggers include providing both an inline SQL string and the `--file` flag simultaneously, or omitting required arguments.

**Example scenario:**

```bash
dbx query my_conn "SELECT 1" --file ./script.sql

```

**Output:**

```json
{"code":"INVALID_ARGUMENT","message":"Provide SQL either inline or with --file, not both."}

```

### INVALID_OPTION

**Thrown at multiple locations: lines 170, 204, 222, 279, 291, 299, and 307** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code indicates an option flag is syntactically correct but its value is illegal. Specific triggers include:
- Unsupported values for `--format` flags
- Missing values after an option flag
- Non-positive integers for `--limit` parameters
- Malformed duration strings
- Using `--allow-dangerous-sql` without enabling `--allow-writes`

**Example scenario:**

```bash
dbx query my_conn "DROP TABLE users;" --allow-dangerous-sql

```

**Output:**

```json
{"code":"INVALID_OPTION","message":"--allow-dangerous-sql requires --allow-writes."}

```

### UNKNOWN_OPTION

**Thrown at line 270** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code indicates the user supplied a flag that the CLI does not recognize, typically caused by typos in command-line flags.

**Example scenario:**

```bash
dbx --unknwon

```

**Output:**

```json
{"code":"UNKNOWN_OPTION","message":"Unknown option: --unknwon"}

```

### CONNECTION_NOT_FOUND

**Thrown at line 341** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code indicates the referenced connection name does not exist in the DBX configuration file. The CLI validates connection names before attempting to establish database connections.

**Example scenario:**

```bash
dbx query unknown_conn "SELECT 1"

```

**Output:**

```json
{"code":"CONNECTION_NOT_FOUND","message":"Connection \"unknown_conn\" not found."}

```

### DBX_NOT_RUNNING

**Thrown at lines 219-220** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code indicates the DBX Desktop bridge process is not reachable when attempting to open a table via `dbx open`. This error specifically occurs when the Desktop application required for the `open` subcommand is not active.

**Example scenario:**

```bash
dbx open my_conn my_table

```

**Output:**

```json
{"code":"DBX_NOT_RUNNING","message":"DBX is not running. Please start DBX first."}

```

### USAGE

**Thrown at line 226** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code indicates the command string does not match any known sub-command. When triggered, the CLI displays the usage help information and exits with the `USAGE` code.

**Example scenario:**

```bash
dbx foobar

```

**Output:**

```

Usage information displayed (code: USAGE)

```

### ERROR

**Fallback at line 229** in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts).

This code serves as a generic catch-all for uncaught exceptions that do not expose a specific `code` property. The CLI prefixes any unexpected exception with `ERROR` to differentiate between known CLI conditions and unexpected failures.

**Example scenario:**

```bash

# Simulated by corrupting the config file

dbx query my_conn "SELECT 1"

```

**Output:**

```json
{"code":"ERROR","message":"..."}

```

## Practical Examples: Triggering DBX CLI Error Codes

The following commands demonstrate how to trigger each error code for testing error handling in your scripts:

```bash

# INVALID_ARGUMENT - mixing inline SQL and --file

dbx query my_conn "SELECT 1" --file ./script.sql

# INVALID_OPTION - dangerous SQL flag without writes flag

dbx query my_conn "DROP TABLE users;" --allow-dangerous-sql

# INVALID_OPTION - unsupported format for context command

dbx context my_conn --format csv

# UNKNOWN_OPTION - typo in flag

dbx --unknwon

# CONNECTION_NOT_FOUND - non-existent connection

dbx query unknown_conn "SELECT 1"

# DBX_NOT_RUNNING - Desktop bridge unavailable

dbx open my_conn my_table

# USAGE - unrecognized command

dbx foobar

```

## Summary

- **Seven distinct error codes** are defined in [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts) through the `CliError` class
- **`INVALID_ARGUMENT`** (lines 164, 284) indicates conflicting or missing arguments
- **`INVALID_OPTION`** (lines 170, 204, 222, 279, 291, 299, 307) indicates illegal flag values
- **`UNKNOWN_OPTION`** (line 270) indicates unrecognized flags
- **`CONNECTION_NOT_FOUND`** (line 341) indicates missing connection configurations
- **`DBX_NOT_RUNNING`** (lines 219-220) indicates the Desktop bridge is unavailable
- **`USAGE`** (line 226) indicates unknown sub-commands
- **`ERROR`** (line 229) serves as the fallback for uncaught exceptions

## Frequently Asked Questions

### What is the difference between INVALID_ARGUMENT and INVALID_OPTION in DBX CLI?

`INVALID_ARGUMENT` refers to problems with command arguments themselves, such as providing both inline SQL and a `--file` flag simultaneously, or missing required positional arguments. `INVALID_OPTION` specifically refers to flag values that are syntactically valid but semantically incorrect, such as providing an unsupported format to `--format` or using `--allow-dangerous-sql` without `--allow-writes`.

### How do I capture DBX CLI error codes in shell scripts?

The DBX CLI outputs JSON-formatted errors to stderr when failures occur. You can capture and parse these codes using standard shell redirection and tools like `jq`. For example: `dbx query conn "SELECT 1" 2>&1 | jq -r '.code'` extracts the error code for conditional logic in your automation scripts.

### What does DBX_NOT_RUNNING mean and how do I fix it?

This error indicates the DBX Desktop bridge process is not accessible when running the `dbx open` command. Unlike other commands that connect directly to databases, the `open` command requires the DBX Desktop application to be running as a bridge. To resolve this, start the DBX Desktop application before executing `dbx open` commands.

### Where are DBX CLI error codes defined in the source code?

All error codes are defined and thrown within [`packages/cli/src/cli.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli.ts) in the t8y2/dbx repository. The `CliError` class handles error construction, while [`packages/cli/src/cli-format.ts`](https://github.com/t8y2/dbx/blob/main/packages/cli/src/cli-format.ts) manages the formatting of error payloads for JSON output. The CLI entry point is declared in [`packages/cli/package.json`](https://github.com/t8y2/dbx/blob/main/packages/cli/package.json) under the `bin` field.