# Common DBX Connection Issues and How to Troubleshoot Them

> Resolve common DBX connection issues like corrupted stores, missing secrets, or proxy problems. Learn to troubleshoot efficiently using inspectConnectionStore and node-core.

- Repository: [skyler/dbx](https://github.com/t8y2/dbx)
- Tags: how-to-guide
- Published: 2026-07-08

---

**Most DBX connection issues stem from a corrupted SQLite connection store, missing secrets in the transport layer, or misconfigured SSH/proxy settings, and can be diagnosed using the `inspectConnectionStore()` API and connection validation methods in the node-core package.**

The t8y2/dbx repository manages database connections through a local **SQLite**-backed connection store that hydrates secrets and normalizes transport layers before establishing physical sockets. When queries fail or connections refuse to establish, the root cause typically lies in one of six categories ranging from missing credential files to network timeouts. Understanding the internal flow—starting with `loadConnections()` in [`packages/node-core/src/connections.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/connections.ts) and ending with driver-specific execution—provides a systematic approach to resolving these failures.

## Connection Store Missing or Corrupted

The UI displays **“No connections”** and API calls to `/api/connection/list` return empty arrays when the local SQLite file is missing or its tables are corrupted.

In [`packages/node-core/src/connections.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/connections.ts), the `inspectConnectionStore()` function checks `dbPathExists` and validates the presence of required tables (`connections`, `connection_secrets`). If the file at `~/.dbx/store.db` (returned by `defaultDbPath()`) is absent or damaged, DBX treats the store as empty.

To recover:

1. Call `inspectConnectionStore()` (exposed via `/api/diagnostics`) to identify whether the file or tables are missing.
2. If the path is wrong, verify it matches `defaultDbPath()`.
3. If tables are corrupted, run `sqlite3 <path> "VACUUM;"` or delete the file to let DBX recreate a fresh store.
4. Re-add connections via the UI or `addConnection()` API.

*Source:* `packages/node-core/src/connections.ts#L30-L62`

## Incorrect Credentials or Missing Secrets

Authentication failures and `ConnectionStoreError` logs indicate that `hydrateTransportLayerSecrets()` could not populate password or SSH key fields from the `connection_secrets` table.

Passwords and sensitive data are stored separately from connection definitions. When `loadConnections()` hydrates a connection, it joins against `connection_secrets`; missing rows leave fields empty, causing drivers to reject login attempts.

To resolve:

1. Query the SQLite store directly: `SELECT * FROM connection_secrets WHERE connection_id = '<id>';`
2. Re-enter credentials via the UI’s “Edit Connection” screen to rewrite values to `connection_secrets`.
3. If importing legacy JSON, verify `ssh_enabled` and `proxy_enabled` sections migrated correctly via `normalizeTransportLayers`.
4. Confirm the `ssl` flag matches server expectations.

*Source:* `packages/node-core/src/connections.ts#L88-L100`

## Transport-Layer Misconfiguration (SSH/Proxy)

Errors like “SOCKS proxy connect failed” or “SSH tunnel error” followed by timeouts originate in `connectionEndpoint()` within [`packages/node-core/src/database.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/database.ts).

This function determines final host/port based on the `transport_layers` JSON. If a layer is disabled, misconfigured, or the host is unreachable, `netConnect()` or the SOCKS library aborts the attempt.

Troubleshooting steps:

1. Run `inspectConnectionStore()` and inspect the `transport_layers` object for the connection.
2. Verify SSH reachability manually: `ssh -p <port> <user>@<host>`.
3. Ensure `proxy_type` is set to `"socks5"` or `"http"` as required.
4. Toggle `expose_lan` in the `ssh_tunnel` object if the database is on the remote LAN.
5. Increase `connectTimeoutSecs` (default **5 seconds**) for high-latency networks.

*Source:* `packages/node-core/src/database.ts#L183-L222`

## Unsupported or Mis-typed DB Type

Immediate errors stating “Unsupported pooled connection type: sqlite” (or similar) occur when `canonicalizeConnection()` encounters an unrecognized `db_type`.

This helper in [`packages/node-core/src/connections.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/connections.ts) rewrites legacy types (e.g., `mysql` with `tdengine` profile) but falls through to an error if the driver is not registered in the backend switch statement.

To fix:

1. Confirm `db_type` matches supported values: `postgres`, `mysql`, `sqlite`, `mongodb`, `redis`, `rqlite`.
2. For TDengine connections, ensure the driver profile is set correctly during `canonicalizeConnection`.
3. When adding custom drivers, register them in [`driver-manifest.test.ts`](https://github.com/t8y2/dbx/blob/main/driver-manifest.test.ts) and update the manifest JSON.

*Source:* `packages/node-core/src/connections.ts#L90-L105`

## Connection Timeout and Network Errors

“Connection lost”, `ECONNRESET`, `EPIPE`, or “connection refused” errors surface when the TCP socket cannot establish under the `connectViaProxy()` retry logic.

While [`packages/node-core/src/database.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/database.ts) uses a `retriable` regex to retry transient failures, persistent network issues or firewall blocks eventually exhaust the retry loop.

Resolution steps:

1. Test basic reachability: `telnet <host> <port>` or `nc -vz <host> <port>`.
2. Verify if the database requires TLS (`ssl: true`).
3. Increase `connectionTimeoutMillis` (default **10,000 ms**) in the connection config for slow-responding servers.
4. Review firewall rules, especially for Docker containers bridging networks.

*Source:* `packages/node-core/src/database.ts#L741-L751`

## Missing or Invalid SSL Certificates

SSL verification failures occur when `ca_cert_path`, `client_cert_path`, or `client_key_path` point to unreadable files or the server rejects the certificate chain.

The `ssl` boolean field is optional; when enabled, DBX validates certificate paths during the TLS handshake in [`packages/node-core/src/connections.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/connections.ts).

Troubleshooting:

1. Confirm certificate files exist on the DBX host and are readable by the process.
2. Temporarily disable `ssl` in the UI to test plain-text connectivity.
3. For PostgreSQL, ensure the connection string includes `sslmode=require` if the server enforces TLS.

*Source:* `packages/node-core/src/connections.ts#L20-L24`

## Diagnostic Code Examples

Use these snippets to programmatically inspect and repair connection state.

### List All Connections

```ts
import { loadConnections } from "dbx/packages/node-core/src/connections.js";

async function listAll() {
  const connections = await loadConnections();
  console.log("Available connections:", connections.map(c => c.name));
}
listAll();

```

This calls `loadConnections()` to read the SQLite store and hydrate secrets from `connection_secrets`.

### Inspect Connection Store Health

```ts
import { inspectConnectionStore } from "dbx/packages/node-core/src/connections.js";

async function diagnose() {
  const diag = await inspectConnectionStore();
  console.log(diag);
  // Example output:
  // { dbPathExists: true, connectionsTableExists: true, connectionRowCount: 2, … }
}
diagnose();

```

Returns flags for `dbPathExists`, table existence, and row counts to pinpoint corruption.

### Add a PostgreSQL Connection

```ts
import { addConnection } from "dbx/packages/node-core/src/connections.js";

async function createPg() {
  const cfg = await addConnection({
    name: "pg-prod",
    db_type: "postgres",
    host: "db.example.com",
    port: 5432,
    username: "admin",
    password: "secret",
    database: "sales",
    ssl: true,
  });
  console.log("Created:", cfg.id);
}
createPg();

```

`addConnection()` writes the definition to the `connections` table and secrets to `connection_secrets`.

### Execute a Query with Connection Validation

```ts
import {
  findConnection,
  listTables,
  describeTable,
  executeQuery,
} from "dbx/packages/node-core/src/web-backend.ts";

async function demo() {
  const conn = await findConnection("pg-prod");
  if (!conn) throw new Error("Connection not found");

  // Triggers ensureConnected() -> /api/connection/connect
  await listTables(conn);

  const cols = await describeTable(conn, "customers");
  console.log("Columns:", cols);

  const result = await executeQuery(conn, "SELECT * FROM customers LIMIT 5");
  console.table(result.rows);
}
demo();

```

`listTables()` invokes `ensureConnected()`, which posts to `/api/connection/connect` and validates the transport layer before executing driver code.

## Summary

- **Connection store corruption** manifests as empty connection lists; use `inspectConnectionStore()` to verify the SQLite file at `~/.dbx/store.db` and recreate if necessary.
- **Missing secrets** in the `connection_secrets` table cause authentication failures; re-enter credentials via the UI or SQL to repopulate.
- **Transport-layer errors** (SSH/proxy) require validating `transport_layers` JSON and verifying network reachability with manual SSH or `telnet` tests.
- **Unsupported DB types** must match the whitelist in `canonicalizeConnection()`; legacy formats require profile migration.
- **Network timeouts** are resolved by increasing `connectionTimeoutMillis` or fixing firewall rules blocking the DBX host.
- **SSL failures** require readable certificate paths and correct `sslmode` settings for the target driver.

## Frequently Asked Questions

### How do I verify my DBX connection store is intact?

Call the `inspectConnectionStore()` function from [`packages/node-core/src/connections.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/connections.ts) or query the `/api/diagnostics` endpoint. This returns boolean flags for `dbPathExists` and `connectionsTableExists`, along with the row count in the `connections` table. If `dbPathExists` is false, check that the path matches `defaultDbPath()` (typically `~/.dbx/store.db`).

### Why does my DBX connection fail with an authentication error even though I saved the password?

Passwords are stored separately in the `connection_secrets` table. If the secret row is missing or the `hydrateTransportLayerSecrets()` function fails to join it during `loadConnections()`, the driver receives an empty string. Open the SQLite file and verify the row exists with `SELECT * FROM connection_secrets WHERE connection_id = '<your-id>';`, or re-enter the password in the UI to force a rewrite.

### How do I fix SSH tunnel or proxy errors in DBX?

Check the `transport_layers` JSON for the connection using `inspectConnectionStore()`. Ensure the `proxy_type` is set to `"socks5"` or `"http"`, verify the SSH server is reachable via `ssh -p <port> <user>@<host>`, and increase `connectTimeoutSecs` beyond the default 5 seconds if operating over high-latency networks. The tunnel logic resides in [`packages/node-core/src/database.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/database.ts) within the `connectionEndpoint()` implementation.

### What causes "Unsupported pooled connection type" errors in DBX?

This error occurs when `canonicalizeConnection()` in [`packages/node-core/src/connections.ts`](https://github.com/t8y2/dbx/blob/main/packages/node-core/src/connections.ts) encounters a `db_type` not recognized by the driver switch statement. Ensure your connection uses supported values such as `postgres`, `mysql`, `sqlite`, `mongodb`, `redis`, or `rqlite`. Custom drivers must be registered in [`driver-manifest.test.ts`](https://github.com/t8y2/dbx/blob/main/driver-manifest.test.ts) and the manifest JSON before they can be instantiated.