tursodatabase/turso · error · Error

unknown error type ${name} from Turso

Error message

unknown error type ${name} from Turso

What it means

This is the async (promise-based) layer's copy of the error-conversion logic in the Turso JavaScript bindings. When a rejected native error carries a code prefixed with '[TURSO_CONVERT_TYPE]', the JS layer maps the trailing name to a registered constructor via convertibleErrorTypes (currently only TypeError). An unregistered name makes createErrorByName throw this 'unknown error type' Error, replacing the original failure. It signals a version skew between the native module and the JS packages, or a library bug - not a caller mistake.

Source

Thrown at bindings/javascript/packages/common/promise.ts:23

const convertibleErrorTypes = { TypeError };
const CONVERTIBLE_ERROR_PREFIX = "[TURSO_CONVERT_TYPE]";

function convertError(err) {
  if ((err.code ?? "").startsWith(CONVERTIBLE_ERROR_PREFIX)) {
    return createErrorByName(
      err.code.substring(CONVERTIBLE_ERROR_PREFIX.length),
      err.message,
    );
  }

  return new SqliteError(err.message, err.code, err.rawCode);
}

function createErrorByName(name, message) {
  const ErrorConstructor = convertibleErrorTypes[name];
  if (!ErrorConstructor) {
    throw new Error(`unknown error type ${name} from Turso`);
  }

  return new ErrorConstructor(message);
}

// The engine returned STEP_SLEEP: its busy handler wants the statement retried
// after a backoff delay. Park the step loop on a timer promise — unlike STEP_IO
// there is no I/O completion coming to wake us up, so waiting on the IO
// notifier would hang (WASM) or spin (native).
function sleepBeforeRetry(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function isQueryOptions(value) {
  return value != null
    && typeof value === "object"
    && !Array.isArray(value)
    && Object.prototype.hasOwnProperty.call(value, "queryTimeout");

View on GitHub (pinned to bad083fafb)

Solutions

1. Align versions: update the native module and all @tursodb JS packages to the same release in one install
2. Nuke stale artifacts: rm -rf node_modules && npm install (or cargo clean for local native builds) to rebuild both halves consistently
3. Verify with a trivial await client.execute('SELECT 1') after realignment to confirm error plumbing is healthy
4. If it persists on matched versions, capture the reported type name and open an upstream issue - the registry is missing it

Example fix

// before: native@2.1.0 emits [TURSO_CONVERT_TYPE]RangeError, js@2.0.0 only knows TypeError
await client.execute('SELECT 1'); // -> Error: unknown error type RangeError from Turso

// after: pin both to the same version in package.json
// "@tursodb/client": "2.1.0", "@tursodb/native-*": "2.1.0"

// No pre-call validation exists: the failure is internal to error conversion.
// At startup, verify the native and JS halves come from one release:
console.assert(pkgVersionsMatch(), 'native/JS binding version skew detected');

function isTursoConversionError(err: unknown): boolean {
  return err instanceof Error && /^unknown error type .+ from Turso$/.test(err.message);
}

try {
  const rs = await client.execute(sql);
} catch (err) {
  if (isTursoConversionError(err)) {
    // Version skew / library bug: escalate, never mask the underlying failure with a retry
    telemetry.report('binding-version-skew', { message: err.message });
    throw err;
  }
  throw err;
}

When it happens

Trigger: An async call (client.execute, db.prepare in promise.ts, batch, or any await on the promise facade) rejects with err.code = '[TURSO_CONVERT_TYPE]<Name>' where <Name> is not 'TypeError'. Occurs when the native artifact and packages/common are built from different revisions, or a new convertible type was added natively without updating the registry at promise.ts.

Common situations: Partial upgrades where @tursodb/native-* and the JS packages come from different releases; custom WASM builds of the native layer; lockfiles resolving mismatched versions after a branch switch; nightly/canary native builds paired with stable JS packages.

Related errors

• unknown error type ${name} from Turso
• The database connection is not open
• The supplied SQL string contains no statements
• Expected first argument to be a function
• Expected first argument to be a string

AI-assisted analysis of tursodatabase/turso@bad083fafb (2026-08-16). Data as JSON: /api/errors/d695a9a5ae5f91e3. Report an issue: GitHub.