{"record":{"id":"dc5dccebf9ebfbb5","repo":"tursodatabase/turso","slug":"remotewritesexperimental-requires-a-non-null-url-dc5dcc","errorCode":null,"errorMessage":"remoteWritesExperimental requires a non-null URL","messagePattern":"remoteWritesExperimental requires a non-null URL","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/sync/packages/wasm/promise-vite-dev-hack.ts","lineNumber":45,"sourceCode":"        async write(path: string, data: Buffer | Uint8Array): Promise<void> {\n            values.set(path, data);\n        }\n    }\n};\n\nasync function init(): Promise<Worker> {\n    await initThreadPool();\n    if (MainWorker == null) {\n        throw new Error(\"panic: MainWorker is not initialized\");\n    }\n    return MainWorker;\n}\n\nfunction resolveUrl(url: string | (() => string | null)): string {\n    if (typeof url === \"function\") {\n        const resolved = url();\n        if (resolved == null) {\n            throw new Error(\"remoteWritesExperimental requires a non-null URL\");\n        }\n        return resolved;\n    }\n    return url;\n}\n\nclass Database extends DatabasePromise {\n    #runner: Runner;\n    #engine: any;\n    #io: ProtocolIo;\n    #guards: SyncEngineGuards;\n    #worker: Worker | null;\n    #remoteWriter: RemoteWriter | null = null;\n    #db: any;\n    constructor(opts: DatabaseOpts) {\n        if (opts.url == null) {\n            const db = new NativeDatabase(opts.path, { tracing: opts.tracing, experimental: opts.experimental }) as any;\n            super(","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/bindings/javascript/sync/packages/wasm/promise-vite-dev-hack.ts#L27-L63","documentation":"DatabaseOpts.url accepts either a plain string or a zero-argument function returning string | null, so callers can resolve the URL lazily (typically from an environment variable). resolveUrl() invokes that function and throws when it returns null, because remoteWritesExperimental needs a concrete remote endpoint to send writes to. A null resolution means configuration is incomplete, and the library fails fast at open time rather than at first write.","triggerScenarios":"Passing `url: () => process.env.TURSO_DB_URL ?? null` (or any function that can return null) while the environment variable is unset; a URL function that reads config that is not yet loaded at database construction time; SSR or test environments where the env var is never injected.","commonSituations":"Missing .env entries in CI or a teammate's machine; deploying with a different env-var name than the code reads (TURSO_DB_URL vs DATABASE_URL); using a function form of url for the first time and forgetting the null branch; preview/staging environments that never received the sync URL.","solutions":["Set the environment variable the URL function reads (e.g. TURSO_DB_URL) in the environment where the database is opened","Pass the URL as a plain string when it is known at build/startup time","Make the function total: `url: () => process.env.TURSO_DB_URL ?? \"https://your-db.turso.io\"` or throw your own descriptive error before Turso does"],"exampleFix":"// before\nconst db = new Database(\"app.db\", {\n  url: () => process.env.TURSO_DB_URL ?? null, // throws when env unset\n  authToken,\n  remoteWritesExperimental: true,\n});\n\n// after\nif (!process.env.TURSO_DB_URL) throw new Error(\"TURSO_DB_URL is required\");\nconst db = new Database(\"app.db\", {\n  url: process.env.TURSO_DB_URL,\n  authToken,\n  remoteWritesExperimental: true,\n});","handlingStrategy":"validation","validationCode":"// Resolve and check the URL yourself before handing it to the constructor\nconst resolveUrl = (url: string | (() => string | null)): string => {\n  const resolved = typeof url === 'function' ? url() : url;\n  if (resolved == null) {\n    throw new Error(`Sync URL resolved to null — check TURSO_DB_URL in ${import.meta.env.MODE} mode`);\n  }\n  return resolved;\n};\n\nconst db = new Database(path, {\n  url: resolveUrl(opts.url),\n  authToken,\n  remoteWritesExperimental: true,\n});","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fail fast at app startup on missing env vars instead of at first database open","Prefer a plain string url when the value is known at build time","Add env-var presence checks to CI for every environment the app deploys to"],"tags":["configuration","url","env-var","wasm","vite","remote-writes"],"backgroundTag":"missing-env-var","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}