{"record":{"id":"c9c293c8444621ad","repo":"tursodatabase/turso","slug":"remotewritesexperimental-requires-a-non-null-url-c9c293","errorCode":null,"errorMessage":"remoteWritesExperimental requires a non-null URL","messagePattern":"remoteWritesExperimental requires a non-null URL","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"bindings/javascript/sync/packages/wasm/promise-turbopack-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/6c7252267988c76e632af00a671e4b9788dfae13/bindings/javascript/sync/packages/wasm/promise-turbopack-hack.ts#L27-L63","documentation":"When remoteWritesExperimental is enabled, the constructor must resolve a concrete remote URL before creating the RemoteWriter. url may be supplied as a lazy resolver function; if calling it yields null or undefined, resolveUrl fails fast (promise-turbopack-hack.ts:41-50) because a null endpoint must never reach the writer. A plain-string url is accepted as-is and never triggers this error.","triggerScenarios":"new Database({ ..., remoteWritesExperimental: true, url: () => import.meta.env.VITE_TURSO_DB_URL }) where the variable is undefined in some build mode; a resolver reading asynchronously-loaded config before it is ready; a placeholder () => null that was never replaced.","commonSituations":"Environment variable defined for dev but missing in preview/production builds; config fetched at runtime so the resolver runs before the value exists; bundler-specific entry (turbopack dev server) where env injection behaves differently than expected.","solutions":["Set the environment/config value the resolver reads so it is non-null in every build mode where remoteWritesExperimental is on","Pass the URL as a plain string when it is already known at construction time","Enable remoteWritesExperimental conditionally, only after your own code confirms the resolved URL is non-null"],"exampleFix":"// before\nconst db = new Database({\n  path: \"local.db\",\n  remoteWritesExperimental: true,\n  url: () => import.meta.env.VITE_TURSO_DB_URL, // undefined in prod\n});\n\n// after\nconst url = import.meta.env.VITE_TURSO_DB_URL;\nif (url == null) throw new Error(\"VITE_TURSO_DB_URL is not set\");\nconst db = new Database({\n  path: \"local.db\",\n  remoteWritesExperimental: true,\n  url,\n});","handlingStrategy":"validation","validationCode":"// Resolve and verify before enabling remote writes\nconst resolvedUrl = typeof url === \"function\" ? url() : url;\nif (resolvedUrl == null) {\n  throw new Error(\"remoteWritesExperimental needs a URL; check your env/config\");\n}\nconst db = new Database({\n  path,\n  url: resolvedUrl,\n  authToken,\n  remoteWritesExperimental: true,\n});","typeGuard":null,"tryCatchPattern":"try {\n  const db = new Database({ path, url, remoteWritesExperimental: true });\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"non-null URL\")) {\n    // URL resolver returned null: fail startup with a clearer message\n    throw new Error(\"Missing remote database URL (check env vars for this build mode)\");\n  }\n  throw err;\n}","preventionTips":["Validate that the env/config value behind the url resolver is set for every build mode before constructing","Pass a plain string url when the endpoint is known statically","Keep a single config module that asserts required variables at startup instead of returning null silently"],"tags":["remote-writes","url","configuration","environment-variables","experimental"],"backgroundTag":"missing-env-var","analyzedSha":"6c7252267988c76e632af00a671e4b9788dfae13","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}