{"record":{"id":"4dc22fa1ac7ce091","repo":"tursodatabase/turso","slug":"database-must-be-connected-before-execution-the-fu","errorCode":null,"errorMessage":"database must be connected before execution the function","messagePattern":"database must be connected before execution the function","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/packages/common/promise.ts","lineNumber":993,"sourceCode":"        fn(result);\n        return result;\n      }\n    },\n    async resolve() {\n      if (promise != null) {\n        return await promise;\n      }\n      let valueResolve, valueReject;\n      promise = new Promise((resolve, reject) => {\n        valueResolve = x => { resolve(x); value = x; }\n        valueReject = reject;\n      });\n      await lazy().then(valueResolve, valueReject);\n      return await promise;\n    },\n    must() {\n      if (value == null) {\n        throw new Error(`database must be connected before execution the function`)\n      }\n      return value;\n    },\n  }\n}\n\nfunction maybeValue<T>(value: T): MaybeLazy<T> {\n  return {\n    apply(fn) { fn(value); },\n    resolve() { return Promise.resolve(value); },\n    must() { return value; },\n  }\n}\n\n/**\n * Statement represents a prepared SQL statement that can be executed.\n */\nclass Statement {","sourceCodeStart":975,"sourceCodeEnd":1011,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/javascript/packages/common/promise.ts#L975-L1011","documentation":"Thrown by the lazy-connection holder (MaybeLazy.must()) that a Statement uses when the underlying native statement handle is still null. The promise API lets you prepare statements against a database whose connection is established lazily; must() resolves that handle on demand and throws this error while the connection promise is pending or has failed. In practice it means a statement method (run/get/all/columns...) ran before the database finished connecting.","triggerScenarios":"Preparing statements at module load and executing them before await db.connect() resolves; connect() failed earlier (network/auth error) so the lazy value was never set; sync-enabled database where connect() performs a network bootstrap and the statement is used mid-bootstrap.","commonSituations":"Server startup that exports prepared statements eagerly; forgetting that the promise API defers connection; connect() errors swallowed so later statement calls fail confusingly; reconnect logic that does not await the new connection.","solutions":["await db.connect() once during initialization, before creating or using any statements.","Make sure connect() failures are surfaced and retried — a failed connect leaves the lazy value null and every later statement call throws.","Re-create statements after a reconnect so they bind to the new connection value."],"exampleFix":"// before\nconst stmt = db.prepare('SELECT 1');\nconst row = await stmt.get(); // throws if lazy connect never finished\n\n// after\nawait db.connect();\nconst stmt = db.prepare('SELECT 1');\nconst row = await stmt.get();","handlingStrategy":"validation","validationCode":"// connect once during app init, before preparing/using statements\nawait db.connect();\nconst stmt = db.prepare('SELECT 1');\nconst row = await stmt.get();","typeGuard":null,"tryCatchPattern":"try {\n  const row = await stmt.get();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('database must be connected')) {\n    await db.connect();\n    return await stmt.get(); // single retry after connecting\n  }\n  throw e;\n}","preventionTips":["Have one initialization path that awaits connect() before anything else touches statements.","Do not export prepared statements at module scope before connect resolves.","Surface connect() failures loudly — a swallowed failure leaves every later statement call broken."],"tags":["connection","lazy-init","statement","javascript"],"backgroundTag":"database-not-connected","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}