{"record":{"id":"921deae5e52a3950","repo":"tursodatabase/turso","slug":"genericfailure-921dea","errorCode":"GenericFailure","errorMessage":"sync engine operation failed: {err}","messagePattern":"sync engine operation failed: (.+?)","errorType":"exception","errorClass":"napi::Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/sync/src/generator.rs","lineNumber":29,"sourceCode":"    fn resume(&mut self, result: Option<String>) -> napi::Result<GeneratorResponse>;\n}\n\nimpl<F: Future<Output = turso_sync_engine::Result<()>>> Generator\n    for genawaiter::sync::Gen<SyncEngineIoResult, turso_sync_engine::Result<()>, F>\n{\n    fn resume(&mut self, error: Option<String>) -> napi::Result<GeneratorResponse> {\n        let result = match error {\n            Some(err) => Err(turso_sync_engine::errors::Error::DatabaseSyncEngineError(\n                format!(\"JsSyncEngineIo error: {err}\"),\n            )),\n            None => Ok(()),\n        };\n        match self.resume_with(result) {\n            genawaiter::GeneratorState::Yielded(SyncEngineIoResult::IO) => {\n                Ok(GeneratorResponse::IO)\n            }\n            genawaiter::GeneratorState::Complete(Ok(())) => Ok(GeneratorResponse::Done),\n            genawaiter::GeneratorState::Complete(Err(err)) => Err(napi::Error::new(\n                napi::Status::GenericFailure,\n                format!(\"sync engine operation failed: {err}\"),\n            )),\n        }\n    }\n}\n\n#[napi]\npub struct SyncEngineChanges {\n    pub(crate) status: Box<Option<DbChangesStatus>>,\n}\n\n#[napi(discriminant = \"type\", object_from_js = false)]\npub enum GeneratorResponse {\n    IO,\n    Done,\n    SyncEngineStats {\n        cdc_operations: i64,","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/javascript/sync/src/generator.rs#L11-L47","documentation":"The JS sync binding drives DatabaseSyncEngine as a coroutine. When the generator completes with Err, resume converts the turso_sync_engine error to a napi GenericFailure: \"sync engine operation failed: {err}\". This is the terminal failure of one sync session, not a single retryable IO step - the completed coroutine cannot be resumed.","triggerScenarios":"The sync coroutine ends in an error state: authentication rejected by the sync server, an unrecoverable protocol or session error, local database state incompatible with the server, or a JS-side IO error fed back in via resume(Some(err)).","commonSituations":"Expired or wrong auth token, sync URL pointing at a non-sync endpoint, server schema changed after an upgrade, or the local replica diverged (e.g. restored from an old backup).","solutions":["Read the wrapped engine error after the prefix - it distinguishes auth, protocol, and engine failures","Refresh the auth token and verify the sync endpoint URL and schema","If the local database diverged, re-bootstrap from the server into a fresh database","Construct a new SyncEngine afterwards - this coroutine is finished"],"exampleFix":"// before\nawait engine.ioLoopAsync(); // rejects with 'sync engine operation failed: ...'\n// after - classify and restart\ntry {\n  await engine.ioLoopAsync();\n} catch (e) {\n  if (String(e.message).startsWith('sync engine operation failed:')) {\n    engine.close();\n    engine = new SyncEngine(opts); // fresh session\n  }\n}","handlingStrategy":"retry","validationCode":"const res = await fetch(syncUrl, { method: 'HEAD' }).catch(() => null);\nif (!res) throw new Error('sync endpoint unreachable before sync start');","typeGuard":"function isSyncEngineFailure(e: unknown): boolean {\n  return e instanceof Error && e.message.startsWith('sync engine operation failed:');\n}","tryCatchPattern":"try { await runSync(engine); } catch (e) { if (isSyncEngineFailure(e)) { engine.close(); engine = new SyncEngine(opts); } else throw e; }","preventionTips":["Rotate auth tokens before expiry","Verify the sync URL and schema match the server","Treat this error as session-terminal: always recreate the engine"],"tags":["sync","javascript","napi","authentication","network"],"backgroundTag":"database-sync-failed","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}