Common DBX Connection Issues and How to Troubleshoot Them

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 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, 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.

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

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

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

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

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

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 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 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 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 and the manifest JSON before they can be instantiated.

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