{"record":{"id":"7728cf953e64f1c3","repo":"tursodatabase/turso","slug":"invalid-config-url-is-required","errorCode":null,"errorMessage":"invalid config: url is required","messagePattern":"invalid config: url is required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"serverless/javascript/src/connection.ts","lineNumber":109,"sourceCode":" * ]);\n *\n * // Option 2: reusable pool for repeated parallel work\n * const pool = Array.from({ length: 4 }, () => connect(config));\n * const results = await Promise.all(\n *   queries.map((sql, i) => pool[i % pool.length].all(sql))\n * );\n * ```\n */\nexport class Connection {\n  private config: Config;\n  private session: Session;\n  private isOpen: boolean = true;\n  private defaultSafeIntegerMode: boolean = false;\n  private execLock: AsyncLock = new AsyncLock();\n\n  constructor(config: Config) {\n    if (!config.url) {\n      throw new Error(\"invalid config: url is required\");\n    }\n    this.config = config;\n    this.session = new Session(config);\n\n    // Define inTransaction property\n    Object.defineProperty(this, 'inTransaction', {\n      get: () => this.session.inTransaction,\n      enumerable: true\n    });\n  }\n\n  /**\n   * Whether the database is currently in a transaction.\n   *\n   * Derived from the server's `get_autocommit` status (refreshed on every\n   * request), so it reflects the connection's real transaction state — the\n   * same as `sqlite3_get_autocommit()` on the native bindings — including\n   * transactions opened with a raw `BEGIN`, not just via `transaction()`.","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/serverless/javascript/src/connection.ts#L91-L127","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nconst db = connect({ url: process.env.TURSO_URL } as Config);\n// Error: invalid config: url is required\n\n// after\nconst url = process.env.TURSO_URL;\nif (!url) throw new Error('TURSO_URL is not set');\nconst db = connect({ url, authToken: process.env.TURSO_AUTH_TOKEN });","handlingStrategy":"validation","validationCode":"function buildConnectionConfig(): Config {\n  const url = process.env.TURSO_URL;\n  if (!url) {\n    throw new Error('TURSO_URL is not set — cannot connect');\n  }\n  return { url, authToken: process.env.TURSO_AUTH_TOKEN };\n}\n\nconst db = connect(buildConnectionConfig());","typeGuard":"function hasUrl(config: unknown): config is Config {\n  return typeof config === 'object' && config !== null && typeof (config as Config).url === 'string' && (config as Config).url.length > 0;\n}","tryCatchPattern":"try {\n  const db = connect(config);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('url is required')) {\n    throw new Error('Database URL missing — check TURSO_URL in this environment');\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["config","validation","env-var","constructor"],"backgroundTag":"missing-required-config-option","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}