{"record":{"id":"b93dbede37517d32","repo":"windmill-labs/windmill","slug":"failed-to-initialize-oracle-client-e","errorCode":null,"errorMessage":"Failed to initialize oracle client: {e}","messagePattern":"Failed to initialize oracle client: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/windmill-worker/src/oracledb_executor.rs","lineNumber":420,"sourceCode":"        .map_err(|x| Error::ExecutionErr(x.to_string()))?\n        .args;\n\n    let reserved_variables =\n        get_reserved_variables(job, &client.token, conn, parent_runnable_path).await?;\n\n    let (query, args_to_skip) =\n        sanitize_and_interpolate_unsafe_sql_args(query, &sig, &job_args, &reserved_variables)?;\n\n    let (_, errors) = get_statement_values(sig.clone(), &job_args, &args_to_skip);\n\n    if !errors.is_empty() {\n        return Err(Error::ExecutionErr(errors.join(\"\\n\")));\n    }\n\n    if !oracle::InitParams::is_initialized() {\n        let _ = oracle::InitParams::new()\n            .oracle_client_lib_dir(ORACLE_LIB_DIR.as_str())\n            .map_err(|e| anyhow!(\"Failed to initialize oracle client: {e}\"))?\n            .init();\n    }\n\n    let oracle_conn = tokio::task::spawn_blocking(|| {\n        oracle::Connection::connect(database.user, database.password, database.database)\n            .map_err(|e| Error::ExecutionErr(e.to_string()))\n    })\n    .await\n    .map_err(to_anyhow)??;\n\n    let conn_a = Arc::new(std::sync::Mutex::new(oracle_conn));\n\n    let queries = parse_sql_blocks(&query, false);\n\n    let result_f = async move {\n        let mut results = vec![];\n        for (i, q) in queries.iter().enumerate() {\n            let (vals, _) = get_statement_values(sig.clone(), &job_args, &args_to_skip);","sourceCodeStart":402,"sourceCodeEnd":438,"githubUrl":"https://github.com/windmill-labs/windmill/blob/e474e8803ce2ff5c2df09a58dab51d45f5c922ca/backend/windmill-worker/src/oracledb_executor.rs#L402-L438","documentation":"The Oracle executor must initialize the Oracle Instant Client native library before opening connections (`oracle::InitParams::init` pointing at `ORACLE_LIB_DIR`). If configuring init params fails (typically the lib dir path doesn't contain the client libraries), the executor returns this error instead of attempting a doomed connect.","triggerScenarios":"`do_oracledb` runs on a worker where `ORACLE_LIB_DIR` is set but doesn't point at a valid Instant Client directory (missing libclntsh / oci.dll), or the oracle crate rejects the config (wrong architecture/version of the client libraries).","commonSituations":"Self-hosted worker without Oracle Instant Client installed; client libs of a major version incompatible with the `oracle` Rust crate; ARM vs x86_64 client mismatch; lib dir env var pointing at the SDK (headers) rather than the lib directory; missing LD_LIBRARY_PATH for transitive deps like libaio.","solutions":["Install Oracle Instant Client (Basic package) on the worker matching the OS/arch.","Point `ORACLE_LIB_DIR` at the directory containing `libclntsh.so` (not the sdk/ or include dir).","Match the Instant Client major version to what the `oracle` crate's bundled OCI expects, and install libaio/ld-linux deps (Debian: `libaio1`).","If already initialized (`is_initialized()` true), the error is skipped — restart the worker after installing the client.","Verify with `ldd libclntsh.so` that all transitive dependencies resolve."],"exampleFix":"// before: ORACLE_LIB_DIR=/opt/oracle/instantclient_21_x/sdk  (headers, no libs)\n// after\n# ORACLE_LIB_DIR=/opt/oracle/instantclient_21_13  (contains libclntsh.so)\nsudo apt-get install -y libaio1","handlingStrategy":"validation","validationCode":"# verify the client library dir before starting the worker\ntest -f \"$ORACLE_LIB_DIR/libclntsh.so\" && echo ok || echo \"ORACLE_LIB_DIR invalid: $ORACLE_LIB_DIR\"\nldd \"$ORACLE_LIB_DIR/libclntsh.so\" | grep 'not found' && echo 'missing transitive deps (libaio?)'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install Oracle Instant Client (Basic, correct arch) in the worker image","Point ORACLE_LIB_DIR at the lib dir containing libclntsh.so, not sdk/","Install libaio and match client major version to the oracle crate","Restart the worker after installing the client"],"tags":["oracle","native-library","configuration","worker"],"backgroundTag":"native-client-library-missing","analyzedSha":"e474e8803ce2ff5c2df09a58dab51d45f5c922ca","analyzedAt":"2026-09-03T12:38:19.024Z","contentChangedAt":"2026-09-03T12:38:19.024Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}