knex/knex · critical · Error

Invalid clientName given: ${clientName}

Error message

Invalid clientName given: ${clientName}

What it means

Same as [11] but located in the TypeScript source `lib/dialects/index.ts` (the compiled `.js` is the file actually executed at runtime). It throws in `getDialectByNameOrAlias()` when the resolved client name is not a known dialect. Functionally identical to error [11]; the `.ts` location appears in source maps/IDE stacks.

Source

Thrown at lib/dialects/index.ts:29

  oracledb: () => require('./oracledb'),
  pgnative: () => require('./pgnative'),
  postgres: () => require('./postgres'),
  redshift: () => require('./redshift'),
  sqlite3: () => require('./sqlite3'),
});

/**
 * Gets the Dialect object with the given client name or throw an
 * error if not found.
 *
 * NOTE: This is a replacement for prior practice of doing dynamic
 * string construction for imports of Dialect objects.
 */
export function getDialectByNameOrAlias(clientName: string) {
  const resolvedClientName = resolveClientNameWithAliases(clientName);
  const dialectLoader = dbNameToDialectLoader[resolvedClientName];
  if (!dialectLoader) {
    throw new Error(`Invalid clientName given: ${clientName}`);
  }
  return dialectLoader();
}

View on GitHub (pinned to e25d54bcb7)

Solutions

1. Use a supported client name/alias (postgres/pg/postgresql, mssql, mysql/mysql2, mariadb, sqlite3/sqlite, better-sqlite3, oracledb, cockroachdb, redshift, pgnative).
2. Normalize the value: trim + lowercase before passing to Knex.
3. Validate against the supported list at startup.
4. Treat this the same as [11] — fix the client name in config.

Example fix

// before
knex({ client: process.env.DB_CLIENT /* 'PostgreSQL ' */ })
// after
knex({ client: process.env.DB_CLIENT.trim().toLowerCase() /* 'postgresql' -> postgres */ })

const { SUPPORTED_CLIENTS } = require('knex/lib/constants');
function normalizeClient(name) {
  const c = String(name || '').trim().toLowerCase();
  if (!SUPPORTED_CLIENTS.includes(c)) throw new Error(`Unsupported Knex client: '${name}'`);
  return c;
}

function isSupportedClient(name: unknown): name is string {
  const list = require('knex/lib/constants').SUPPORTED_CLIENTS as string[];
  return typeof name === 'string' && list.includes(name.trim().toLowerCase());
}

When it happens

Trigger: Same as [11]: unknown/typo'd client name (`'postgre'`, `'mongo'`, `'PG-NATIVE'`), untrimmed/uncased value from config, or an alias not recognized by `resolveClientNameWithAliases`.

Common situations: TypeScript project reading the stack trace through source maps; IDE 'Go to definition' landing on the `.ts`; otherwise identical real-world causes as [11].

Related errors

• knex: Required configuration option 'client' is missing.
• Invalid clientName given: ${clientName}
• The '${this.driverName || 'base'}' dialect does not support
• knex: Unknown configuration option 'client' value ${clientNa
• ${message} ${e.message}

AI-assisted analysis of knex/knex@e25d54bcb7 (2026-08-03). Data as JSON: /data/errors/72bf0c2d6a1d6ec8.json. Report an issue: GitHub.