tursodatabase/turso · error · LibsqlError

MISSING_URL

MISSING_URL

Error message

Missing required 'url' configuration option

What it means

Thrown by the serverless compatibility layer's client constructor validation (compat.ts) when the config object has no 'url'. The compat layer only accepts 'url', 'authToken', and 'remoteEncryptionKey', and 'url' is the single required option, so an empty or missing url fails fast at construction time with code MISSING_URL before any network I/O happens.

Source

Thrown at serverless/javascript/src/compat.ts:223

    }
    if (config.fetch !== undefined) {
      unsupportedOptions.push({ key: 'fetch', value: config.fetch });
    }
    if (config.concurrency !== undefined) {
      unsupportedOptions.push({ key: 'concurrency', value: config.concurrency });
    }

    if (unsupportedOptions.length > 0) {
      const optionsList = unsupportedOptions.map(opt => `'${opt.key}'`).join(', ');
      throw new LibsqlError(
        `Unsupported configuration options: ${optionsList}. Only 'url', 'authToken', and 'remoteEncryptionKey' are supported in the serverless compatibility layer.`,
        "UNSUPPORTED_CONFIG"
      );
    }

    // Validate required options
    if (!config.url) {
      throw new LibsqlError("Missing required 'url' configuration option", "MISSING_URL");
    }
  }

  get closed(): boolean {
    return this._closed;
  }

  get protocol(): string {
    return "http";
  }

  private normalizeStatement(stmt: InStatement): { sql: string; args: any[] } {
    if (typeof stmt === 'string') {
      return { sql: stmt, args: [] };
    }
    
    const args = stmt.args || [];
    if (Array.isArray(args)) {

View on GitHub (pinned to bad083fafb)

Solutions

1. Set the url option explicitly, usually from the environment: createClient({ url: process.env.TURSO_URL, authToken: process.env.TURSO_AUTH_TOKEN })
2. Verify the environment variable exists at process start and fail fast with a clear message if TURSO_URL is unset
3. Ensure .env loading (e.g. dotenv/config) happens before the module that constructs the client is imported
4. Check for typos in the env var name across local, CI, and deploy environments

Example fix

// before
const client = createClient({ authToken: process.env.TURSO_AUTH_TOKEN });
// throws LibsqlError MISSING_URL: Missing required 'url' configuration option

// after
if (!process.env.TURSO_URL) {
  throw new Error('TURSO_URL is not set — configure it before creating the client');
}
const client = createClient({
  url: process.env.TURSO_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});

function assertClientConfig(config: Partial<Config>): Config {
  if (typeof config.url !== 'string' || config.url.length === 0) {
    throw new Error('TURSO_URL is not set — add it to the environment before creating the client');
  }
  return config as Config;
}

const client = createClient(
  assertClientConfig({ url: process.env.TURSO_URL, authToken: process.env.TURSO_AUTH_TOKEN }),
);

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

try {
  const client = createClient(config);
} catch (e) {
  if (e instanceof LibsqlError && e.code === 'MISSING_URL') {
    throw new Error('Database URL missing — check TURSO_URL in this environment');
  }
  throw e;
}

When it happens

Trigger: Calling createClient(new Client(...)) with an empty object, with only { authToken }, or with url set to an empty string (any falsy value fails the !config.url check). Most commonly: building config from process.env.TURSO_URL when that variable is undefined because it was never exported or the .env file was not loaded before construction.

Common situations: Missing or misnamed environment variable in CI, Docker, or serverless deployments (TURSO_DB_URL vs TURSO_URL); .env loaded after the client module is imported at top level; a config spread like { ...base, url: undefined } that clobbers url; porting code from @libsql/client where the url was optional for local file databases.

Related errors

• invalid config: url is required
• retryFetch: attempts must be a finite integer >= 1, got ${at
• remoteWritesExperimental requires a non-null URL
• remoteWritesExperimental requires a non-null URL
• remoteWritesExperimental requires a non-null URL

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