{"record":{"id":"4057ad9709d5679a","repo":"tursodatabase/turso","slug":"genericfailure","errorCode":"GenericFailure","errorMessage":"{message}: {e}","messagePattern":"\\{message\\}: \\{e\\}","errorType":"exception","errorClass":"napi::Error","httpStatus":null,"severity":"error","filePath":"bindings/javascript/src/lib.rs","lineNumber":229,"sourceCode":"        Ok(turso_core::StepResult::IO) => Ok((STEP_IO, 0)),\n        Ok(turso_core::StepResult::Yield) => Ok((STEP_SLEEP, 1)),\n        Ok(turso_core::StepResult::Sleep { duration }) => {\n            // Round sub-millisecond delays up to 1ms: a 0ms setTimeout would\n            // make the JS step loop spin without letting the backoff expire.\n            let sleep_ms = duration.as_millis().clamp(1, u32::MAX as u128) as u32;\n            Ok((STEP_SLEEP, sleep_ms))\n        }\n        Ok(turso_core::StepResult::Done) => Ok((STEP_DONE, 0)),\n        Ok(turso_core::StepResult::Interrupt) => {\n            Err(create_generic_error(\"statement was interrupted\"))\n        }\n        Ok(turso_core::StepResult::Busy) => Err(create_generic_error(\"database is locked\")),\n        Err(e) => Err(to_generic_error(\"step failed\", e)),\n    }\n}\n\nfn to_generic_error<E: std::error::Error>(message: &str, e: E) -> napi::Error {\n    Error::new(Status::GenericFailure, format!(\"{message}: {e}\"))\n}\n\nfn to_error<E: std::error::Error>(status: napi::Status, message: &str, e: E) -> napi::Error {\n    Error::new(status, format!(\"{message}: {e}\"))\n}\n\nfn create_generic_error(message: &str) -> napi::Error {\n    Error::new(Status::GenericFailure, message)\n}\n\nfn create_error(status: napi::Status, message: &str) -> napi::Error {\n    Error::new(status, message)\n}\n\nfn query_timeout_duration(timeout_ms: u32) -> Option<std::time::Duration> {\n    if timeout_ms > 0 {\n        Some(std::time::Duration::from_millis(timeout_ms as u64))\n    } else {","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/bindings/javascript/src/lib.rs#L211-L247","documentation":"Node.js (napi) binding error wrapper. When stepping a prepared statement fails inside the native engine, to_generic_error(\"step failed\", e) re-throws the underlying turso_core error as a napi GenericFailure with message \"step failed: <cause>\". The prefix only localizes the failure to the VDBE step loop; the real reason is the text after the colon.","triggerScenarios":"stmt.step() (or any JS API that steps a statement) returns Err from turso_core: a page read fails with an I/O error, the statement is interrupted mid-execution, the database file is corrupted, or memory is exhausted while materializing rows.","commonSituations":"Database file moved, deleted, or on an unplugged disk between prepare and step; another thread closes the connection or interrupts during a long query; corrupted database after a crash; or a native/JS binding version mismatch.","solutions":["Read the text after \"step failed:\" - it is the verbatim native error (e.g. \"Disk I/O error\", \"Interrupted\") and names the real cause","If I/O related: verify the database path, file permissions, and disk health","If interrupted or locked: stop closing or interrupting the connection from other threads while a step is in flight","Reinstall the native package so the JS wrapper and native engine versions match"],"exampleFix":"// before\nwhile (stmt.step()) { /* ... */ }\n// after - surface the native cause\ntry {\n  while (stmt.step()) { /* ... */ }\n} catch (e) {\n  if (String(e.message).startsWith('step failed:')) {\n    throw new Error('engine step failure: ' + e.message.slice('step failed:'.length));\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isStepFailure(e: unknown): boolean {\n  return e instanceof Error && e.message.startsWith('step failed:');\n}","tryCatchPattern":"try { stmt.step(); } catch (e) { if (isStepFailure(e)) { /* the suffix is the real native error - log and decide */ } throw e; }","preventionTips":["Keep the connection open and untouched while statements are stepped from JS","Verify the database file stays readable for the process's lifetime","Pin matching versions of the JS wrapper and native module"],"tags":["javascript","node","napi","bindings","statement-execution"],"backgroundTag":"query-execution-failed","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}