tursodatabase/turso · error · TypeError

Expected first argument to be a string

Error message

Expected first argument to be a string

What it means

Thrown by Database.pragma() when the first argument (the pragma source) is not a string. pragma() interpolates the value directly into `PRAGMA ${source}` and executes it, so it must be a string like 'journal_mode' or 'user_version = 1'. Any other type is rejected before reaching prepare().

Source

Thrown at bindings/javascript/packages/common/compat.ts:213

    const properties = {
      default: { value: wrapTxn("") },
      deferred: { value: wrapTxn("DEFERRED") },
      immediate: { value: wrapTxn("IMMEDIATE") },
      exclusive: { value: wrapTxn("EXCLUSIVE") },
      database: { value: this, enumerable: true },
    };
    Object.defineProperties(properties.default.value, properties);
    Object.defineProperties(properties.deferred.value, properties);
    Object.defineProperties(properties.immediate.value, properties);
    Object.defineProperties(properties.exclusive.value, properties);
    return properties.default.value;
  }

  pragma(source, options) {
    if (options == null) options = {};

    if (typeof source !== "string")
      throw new TypeError("Expected first argument to be a string");

    if (typeof options !== "object")
      throw new TypeError("Expected second argument to be an options object");

    const pragma = `PRAGMA ${source}`;

    const stmt = this.prepare(pragma);
    try {
      const results = stmt.all();
      return results;
    } finally {
      stmt.close();
    }
  }

  backup(filename, options) {
    throw new Error("not implemented");
  }

View on GitHub (pinned to bad083fafb)

Solutions

1. Pass the pragma as a string: db.pragma('journal_mode')
2. Coerce known inputs explicitly: db.pragma(String(name))
3. Validate config-provided pragma names against a whitelist of strings before use
4. For assignments, include the value in the string: db.pragma('user_version = 2')

Example fix

// before
db.pragma(pragmaNameFromConfig); // number or undefined from JSON

// after
if (typeof pragmaNameFromConfig !== 'string') throw new TypeError('pragma name must be a string');
db.pragma(pragmaNameFromConfig);

function pragma(db: Database, source: string) {
  if (typeof source !== 'string' || source.length === 0) {
    throw new TypeError(`pragma source must be a non-empty string, got ${typeof source}`);
  }
  return db.pragma(source);
}

function isPragmaName(source: unknown): source is string {
  return typeof source === 'string' && /^[a-z_][a-z0-9_]*(\s*=\s*.+)?$/i.test(source.trim());
}

When it happens

Trigger: Calling db.pragma(123), db.pragma(null), or db.pragma(['journal_mode']); passing a computed value that resolves to a non-string (e.g. a pragma name read from JSON config typed as number); template-literal mistakes that produce an array or object.

Common situations: Reading pragma names from configuration files where a value like user_version is parsed as a number; passing a Pragma name variable that was shadowed or never defined; porting code that used a different SQLite API taking an options object as the first argument.

Related errors

• Expected second argument to be an options object
• The supplied SQL string contains no statements
• Expected first argument to be a function
• Expected first argument to be an array of statements
• The database connection is not open

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