tursodatabase/turso · error · Error

unknown error type ${name} from Turso

Error message

unknown error type ${name} from Turso

What it means

This error is thrown by the internal error-conversion layer in the Turso JavaScript bindings. When the native engine reports an error whose code starts with the marker prefix '[TURSO_CONVERT_TYPE]', the JS layer looks up the trailing type name (e.g. 'TypeError') in a small registry that currently only contains TypeError. If the name is not registered, conversion fails and this 'unknown error type' Error is thrown, discarding the original error object. It almost always indicates a mismatch between the native module version and the JS package version, or a library bug, rather than a mistake in your code.

Source

Thrown at bindings/javascript/packages/common/compat.ts:22

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);
}

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

function splitBindParameters(bindParameters) {
  if (bindParameters.length === 0) {
    return { params: undefined, queryOptions: undefined };
  }
  if (bindParameters.length > 1 && isQueryOptions(bindParameters[bindParameters.length - 1])) {
    return {

View on GitHub (pinned to bad083fafb)

Solutions

1. Update the native module and the JS packages together (e.g. npm update @tursodb/client @tursodb/native-* / the web/terminal package) so both sides agree on the convertible error registry
2. Clear node_modules and lockfile entries and reinstall to eliminate a stale mixed install: rm -rf node_modules package-lock.json && npm install
3. If versions match and it still reproduces, capture the underlying err.code name and file an issue against the tursodb repository - the registry at compat.ts:5 is missing that entry
4. As a stopgap, wrap database calls in try/catch and treat this error as a fatal library-state error rather than a SQL error

Example fix

// before: mixed versions, native emits [TURSO_CONVERT_TYPE]RangeError
// -> throws Error: unknown error type RangeError from Turso

// after: reinstall matching versions so the registry knows the type
// rm -rf node_modules package-lock.json && npm install

// No caller-side validation possible - the condition is internal to the library.
// Sanity-check version alignment at startup instead:
import { versions } from './native-version.js';
if (versions.native !== versions.js) throw new Error('native/JS binding version skew');

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

try {
  await client.execute(sql);
} catch (err) {
  if (isTursoConversionError(err)) {
    // Library/version problem: report it with the original context, do not retry
    throw new Error(`Binding error-conversion failed; check native/JS versions: ${err.message}`);
  }
  throw err;
}

When it happens

Trigger: A native call (db.prepare, db.exec, Statement.run/get/all/iterate/bind, batch) rejects with err.code = '[TURSO_CONVERT_TYPE]<Name>' where <Name> is anything other than 'TypeError' (e.g. RangeError, SyntaxError, or a mangled/empty name). This happens when the native bindings and the @tursodb JS packages are upgraded out of sync, or when a new convertible error type was added natively without updating convertibleErrorTypes in compat.ts:5.

Common situations: Mixed versions after a partial upgrade (native @tursodb/native-* module newer or older than packages/common); installing the JS SDK with a pinned old native artifact; custom builds of the native module against a newer engine that emits new error type markers; corrupted error propagation in WASM builds.

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/513fc2fa292fced7. Report an issue: GitHub.