tursodatabase/turso · error · LibsqlError

UNSUPPORTED_CONFIG

UNSUPPORTED_CONFIG

Error message

Unsupported configuration options: ${optionsList}. Only 'url', 'authToken', and 'remoteEncryptionKey' are supported in the serverless compatibility layer.

What it means

The serverless JavaScript compatibility layer (createClient shim in serverless/javascript/src/compat.ts) validates the config in its constructor and only accepts url, authToken, and remoteEncryptionKey. Passing any of encryptionKey, syncUrl, syncInterval, readYourWrites, offline, tls, intMode, fetch, or concurrency throws a LibsqlError with code 'UNSUPPORTED_CONFIG' listing the offending keys. It fails fast at client construction, before any network call.

Source

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

    if (config.offline !== undefined) {
      unsupportedOptions.push({ key: 'offline', value: config.offline });
    }
    if (config.tls !== undefined) {
      unsupportedOptions.push({ key: 'tls', value: config.tls });
    }
    if (config.intMode !== undefined) {
      unsupportedOptions.push({ key: 'intMode', value: config.intMode });
    }
    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";
  }

View on GitHub (pinned to bad083fafb)

Solutions

Remove the listed unsupported keys — keep only url, authToken, and remoteEncryptionKey
For intMode: convert BigInt values manually after reads instead of configuring integer mode
For custom fetch/proxy needs: use the full @libsql/client package instead of this compatibility layer
For embedded-replica/sync features (syncUrl, offline): use the sync SDK's connect(), not this compat layer

Example fix

// before
const client = createClient({
  url: 'libsql://my-db.turso.io',
  authToken: token,
  syncUrl: 'https://sync.example.com',
  intMode: 'number',
  concurrency: 5,
}); // LibsqlError: Unsupported configuration options: 'syncUrl', 'intMode', 'concurrency'

// after
const client = createClient({
  url: 'libsql://my-db.turso.io',
  authToken: token,
});

Defensive patterns

Strategy: validation

Validate before calling

const SUPPORTED = new Set(['url', 'authToken', 'remoteEncryptionKey']);

function toCompatConfig(config: Record<string, unknown>) {
  const unsupported = Object.keys(config).filter(k => !SUPPORTED.has(k) && config[k] !== undefined);
  if (unsupported.length > 0) {
    throw new Error(`This layer ignores: ${unsupported.join(', ')} — dropping them`);
  }
  return config as { url: string; authToken?: string; remoteEncryptionKey?: string };
}

Type guard

function isSupportedCompatConfig(c: object): c is { url: string; authToken?: string; remoteEncryptionKey?: string } {
  const allowed = ['url', 'authToken', 'remoteEncryptionKey'];
  return Object.keys(c).every(k => allowed.includes(k));
}

Try / catch

try {
  client = createClient(rawConfig);
} catch (e) {
  if ((e as { code?: string }).code === 'UNSUPPORTED_CONFIG') {
    const { url, authToken, remoteEncryptionKey, ...rest } = rawConfig;
    console.warn('dropped unsupported options:', Object.keys(rest));
    client = createClient({ url, authToken, remoteEncryptionKey });
  } else throw e;
}

Prevention

Restrict compat-layer configs to url, authToken, remoteEncryptionKey by construction (a typed factory)
Don't share one config object between the sync SDK and this compat layer — their option sets differ
Handle BigInt conversion in app code instead of passing intMode
Check the LibsqlError code field: UNSUPPORTED_CONFIG means config shape, not connectivity

When it happens

Trigger: createClient({ url, authToken, intMode: 'bigint' }) copied from @libsql/client code; passing a custom fetch or concurrency (common in libsql client configs); copying embedded-replica options (syncUrl, offline, readYourWrites) from the native sync SDK's connect() call into the compat layer's createClient().

Common situations: Porting an existing @libsql/client app to the serverless compat layer; config objects shared between the sync SDK and the serverless client; TypeScript configs built for the wider libsql Config type being reused here.

Related errors

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