typeorm/typeorm · error · TypeORMError

Driver must define supportedIsolationLevels to use isolation

Error message

Driver must define supportedIsolationLevels to use isolationLevel option

What it means

Thrown by validateIsolationLevel when an isolationLevel is supplied but the driver's supportedIsolationLevels property is missing or not an array. The validator is called during transaction setup; it expects each driver to declare which isolation levels it supports. A missing declaration indicates a misconfigured or incomplete driver implementation.

Source

Thrown at src/driver/validate-isolation-level.ts:18

import { TypeORMError } from "../error/TypeORMError"
import type { IsolationLevel } from "./types/IsolationLevel"

/**
 * Validates that the given isolation level is in the provided list of supported levels.
 * Throws a TypeORMError if not supported.
 *
 * @param supported
 * @param isolationLevel
 */
export const validateIsolationLevel = (
    supported: readonly IsolationLevel[],
    isolationLevel?: IsolationLevel,
): void => {
    if (!isolationLevel) return

    if (!supported || !Array.isArray(supported)) {
        throw new TypeORMError(
            `Driver must define supportedIsolationLevels to use isolationLevel option`,
        )
    }

    if (!supported.includes(isolationLevel)) {
        throw new TypeORMError(
            `${isolationLevel} isolation level is not supported`,
        )
    }
}

View on GitHub (pinned to 04ff4daedc)

Solutions

Ensure you are using a first-party, up-to-date driver that defines supportedIsolationLevels (check the driver source for the property).
If using a custom driver, add supportedIsolationLevels: [...] to the driver class listing the supported levels.
Drop the isolationLevel argument from your transaction call if the driver cannot support it.

Example fix

// before — custom driver missing the property
class MyDriver implements Driver {
  // supportedIsolationLevels not defined
}
await dataSource.transaction("SERIALIZABLE", async (em) => { ... })
// after
class MyDriver implements Driver {
  supportedIsolationLevels: IsolationLevel[] = ["READ UNCOMMITTED","READ COMMITTED","REPEATABLE READ","SERIALIZABLE"]
}

Defensive patterns

Strategy: validation

Validate before calling

const supported = (dataSource.driver as any).supportedIsolationLevels
if (!Array.isArray(supported)) {
  throw new Error('This driver does not declare supportedIsolationLevels — cannot use isolation levels')
}
await dataSource.transaction('SERIALIZABLE', async (em) => { ... })

Type guard

function driverSupportsIsolationLevels(driver: unknown): boolean {
  return Array.isArray((driver as any)?.supportedIsolationLevels)
}

Try / catch

try {
  await dataSource.transaction('SERIALIZABLE', cb)
} catch (e) {
  if (e instanceof TypeORMError && /supportedIsolationLevels/.test(e.message)) {
    await dataSource.transaction(cb) // fall back to default isolation
  } else throw e
}

Prevention

Check that dataSource.driver.supportedIsolationLevels is a non-empty array before passing an isolation level.
Keep custom drivers up to date with the Driver interface.
Avoid isolation-level arguments for drivers that don't support them.

When it happens

Trigger: Passing an isolationLevel to DataSource.transaction() or queryRunner.startTransaction() while using a driver that does not define supportedIsolationLevels. Most commonly happens with a custom/third-party driver, an outdated driver version, or a driver stub that doesn't implement the full Driver interface.

Common situations: Using a custom or community driver that hasn't implemented supportedIsolationLevels; upgrading TypeORM and a driver adapter hasn't caught up; mocking a driver in tests without providing the array; passing an isolation level to a driver (like some older builds) that lacks the property.

Related errors

AI-assisted analysis of typeorm/typeorm@04ff4daedc (2026-08-03). Data as JSON: /data/errors/34772a460fb608a2.json. Report an issue: GitHub.