tursodatabase/turso · error · Error

database must be connected before execution the function

Error message

database must be connected before execution the function

What it means

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.

Source

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

        fn(result);
        return result;
      }
    },
    async resolve() {
      if (promise != null) {
        return await promise;
      }
      let valueResolve, valueReject;
      promise = new Promise((resolve, reject) => {
        valueResolve = x => { resolve(x); value = x; }
        valueReject = reject;
      });
      await lazy().then(valueResolve, valueReject);
      return await promise;
    },
    must() {
      if (value == null) {
        throw new Error(`database must be connected before execution the function`)
      }
      return value;
    },
  }
}

function maybeValue<T>(value: T): MaybeLazy<T> {
  return {
    apply(fn) { fn(value); },
    resolve() { return Promise.resolve(value); },
    must() { return value; },
  }
}

/**
 * Statement represents a prepared SQL statement that can be executed.
 */
class Statement {

View on GitHub (pinned to bad083fafb)

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.

Example fix

// before
const stmt = db.prepare('SELECT 1');
const row = await stmt.get(); // throws if lazy connect never finished

// after
await db.connect();
const stmt = db.prepare('SELECT 1');
const row = await stmt.get();

Defensive patterns

Strategy: validation

Validate before calling

// connect once during app init, before preparing/using statements
await db.connect();
const stmt = db.prepare('SELECT 1');
const row = await stmt.get();

Try / catch

try {
  const row = await stmt.get();
} catch (e) {
  if (e instanceof Error && e.message.includes('database must be connected')) {
    await db.connect();
    return await stmt.get(); // single retry after connecting
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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