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

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 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. 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, 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 to indicate distinct failure conditions.

INVALID_ARGUMENT

Thrown at lines 164 and 284 in 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:

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

Output:

{"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.

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:

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

Output:

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

UNKNOWN_OPTION

Thrown at line 270 in 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:

dbx --unknwon

Output:

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

CONNECTION_NOT_FOUND

Thrown at line 341 in 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:

dbx query unknown_conn "SELECT 1"

Output:

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

DBX_NOT_RUNNING

Thrown at lines 219-220 in 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:

dbx open my_conn my_table

Output:

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

USAGE

Thrown at line 226 in 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:

dbx foobar

Output:

Usage information displayed (code: USAGE)

ERROR

Fallback at line 229 in 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:

# Simulated by corrupting the config file

dbx query my_conn "SELECT 1"

Output:

{"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:

# 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 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 in the t8y2/dbx repository. The CliError class handles error construction, while 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 under the bin field.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}