{"record":{"id":"513fc2fa292fced7","repo":"tursodatabase/turso","slug":"unknown-error-type-name-from-turso","errorCode":null,"errorMessage":"unknown error type ${name} from Turso","messagePattern":"unknown error type (.+?) from Turso","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/packages/common/compat.ts","lineNumber":22,"sourceCode":"\nconst convertibleErrorTypes = { TypeError };\nconst CONVERTIBLE_ERROR_PREFIX = \"[TURSO_CONVERT_TYPE]\";\n\nfunction convertError(err) {\n  if ((err.code ?? \"\").startsWith(CONVERTIBLE_ERROR_PREFIX)) {\n    return createErrorByName(\n      err.code.substring(CONVERTIBLE_ERROR_PREFIX.length),\n      err.message,\n    );\n  }\n\n  return new SqliteError(err.message, err.code, err.rawCode);\n}\n\nfunction createErrorByName(name, message) {\n  const ErrorConstructor = convertibleErrorTypes[name];\n  if (!ErrorConstructor) {\n    throw new Error(`unknown error type ${name} from Turso`);\n  }\n\n  return new ErrorConstructor(message);\n}\n\nfunction isQueryOptions(value) {\n  return value != null\n    && typeof value === \"object\"\n    && !Array.isArray(value)\n    && Object.prototype.hasOwnProperty.call(value, \"queryTimeout\");\n}\n\nfunction splitBindParameters(bindParameters) {\n  if (bindParameters.length === 0) {\n    return { params: undefined, queryOptions: undefined };\n  }\n  if (bindParameters.length > 1 && isQueryOptions(bindParameters[bindParameters.length - 1])) {\n    return {","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/javascript/packages/common/compat.ts#L4-L40","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Clear node_modules and lockfile entries and reinstall to eliminate a stale mixed install: rm -rf node_modules package-lock.json && npm install","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","As a stopgap, wrap database calls in try/catch and treat this error as a fatal library-state error rather than a SQL error"],"exampleFix":"// before: mixed versions, native emits [TURSO_CONVERT_TYPE]RangeError\n// -> throws Error: unknown error type RangeError from Turso\n\n// after: reinstall matching versions so the registry knows the type\n// rm -rf node_modules package-lock.json && npm install","handlingStrategy":"try-catch","validationCode":"// No caller-side validation possible - the condition is internal to the library.\n// Sanity-check version alignment at startup instead:\nimport { versions } from './native-version.js';\nif (versions.native !== versions.js) throw new Error('native/JS binding version skew');","typeGuard":"function isTursoConversionError(err: unknown): boolean {\n  return err instanceof Error && /^unknown error type .+ from Turso$/.test(err.message);\n}","tryCatchPattern":"try {\n  await client.execute(sql);\n} catch (err) {\n  if (isTursoConversionError(err)) {\n    // Library/version problem: report it with the original context, do not retry\n    throw new Error(`Binding error-conversion failed; check native/JS versions: ${err.message}`);\n  }\n  throw err;\n}","preventionTips":["Install the native module and JS packages from the same release, pinned in the lockfile","Run a smoke query (SELECT 1) in a startup health check to surface error-path breakage early","Treat this error as an operations alert, not a SQL failure - log it distinctly"],"tags":["turso","javascript","bindings","error-conversion","version-mismatch"],"backgroundTag":"unknown-error-code-mapping","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}