What causes "invalid config: url is required" in tursodatabase/turso?

Pass a concrete url: connect({ url: process.env.TURSO_URL!, ... })

tursodatabase/turso · error · Error

invalid config: url is required

Error message

invalid config: url is required

What it means

The Connection constructor (connection.ts) throws a plain Error 'invalid config: url is required' synchronously when config.url is falsy. Unlike the compat layer, this native-style API validates with a generic Error (no LibsqlError/code), so callers must match on message or validate inputs themselves. It fails before any Session work begins.

Source

Thrown at serverless/javascript/src/connection.ts:109

 * ]);
 *
 * // Option 2: reusable pool for repeated parallel work
 * const pool = Array.from({ length: 4 }, () => connect(config));
 * const results = await Promise.all(
 *   queries.map((sql, i) => pool[i % pool.length].all(sql))
 * );
 * ```
 */
export class Connection {
  private config: Config;
  private session: Session;
  private isOpen: boolean = true;
  private defaultSafeIntegerMode: boolean = false;
  private execLock: AsyncLock = new AsyncLock();

  constructor(config: Config) {
    if (!config.url) {
      throw new Error("invalid config: url is required");
    }
    this.config = config;
    this.session = new Session(config);

    // Define inTransaction property
    Object.defineProperty(this, 'inTransaction', {
      get: () => this.session.inTransaction,
      enumerable: true
    });
  }

  /**
   * Whether the database is currently in a transaction.
   *
   * Derived from the server's `get_autocommit` status (refreshed on every
   * request), so it reflects the connection's real transaction state — the
   * same as `sqlite3_get_autocommit()` on the native bindings — including
   * transactions opened with a raw `BEGIN`, not just via `transaction()`.

View on GitHub (pinned to bad083fafb)

Solutions

Pass a concrete url: connect({ url: process.env.TURSO_URL!, ... })
Validate at boot: if (!process.env.TURSO_URL) throw new Error('TURSO_URL missing') before constructing
Make sure env loading happens before the module that creates the connection is evaluated
Double-check the env var name in every environment (local, CI, prod)

Example fix

// before
const db = connect({ url: process.env.TURSO_URL } as Config);
// Error: invalid config: url is required

// after
const url = process.env.TURSO_URL;
if (!url) throw new Error('TURSO_URL is not set');
const db = connect({ url, authToken: process.env.TURSO_AUTH_TOKEN });

Defensive patterns

Strategy: validation

Validate before calling

function buildConnectionConfig(): Config {
  const url = process.env.TURSO_URL;
  if (!url) {
    throw new Error('TURSO_URL is not set — cannot connect');
  }
  return { url, authToken: process.env.TURSO_AUTH_TOKEN };
}

const db = connect(buildConnectionConfig());

Type guard

function hasUrl(config: unknown): config is Config {
  return typeof config === 'object' && config !== null && typeof (config as Config).url === 'string' && (config as Config).url.length > 0;
}

Try / catch

try {
  const db = connect(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('url is required')) {
    throw new Error('Database URL missing — check TURSO_URL in this environment');
  }
  throw e;
}

Prevention

Fail fast on missing env vars at boot instead of deep inside connection setup
Centralize config construction in one validated function
Ensure env loading precedes module evaluation of the connection
Add a CI smoke test that constructs the connection to catch env drift before deploy

When it happens

Trigger: connect({ url: undefined }) or new Connection({}) — typically because the url came from an env var that is not set, is an empty string, or a config object was built conditionally and the url branch did not run.

Common situations: Missing TURSO_URL in deployed environments; env var name drift between local and CI; constructing the connection at module top level before env loading completes; spreading a partial config over a default without a url.

Related errors

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