{"record":{"id":"909b1079e54d2671","repo":"mudler/LocalAI","slug":"ds4-worker-failed-to-open-engine","errorCode":null,"errorMessage":"ds4-worker: failed to open engine\n","messagePattern":"ds4-worker: failed to open engine\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"backend/cpp/ds4/worker_main.c","lineNumber":117,"sourceCode":"    if (opt.distributed.role != DS4_DISTRIBUTED_WORKER) {\n        fprintf(stderr, \"ds4-worker: --role worker is required\\n\");\n        return 2;\n    }\n    if (!opt.model_path) {\n        fprintf(stderr, \"ds4-worker: --model is required\\n\");\n        return 2;\n    }\n\n    char prep_err[256] = {0};\n    if (ds4_dist_prepare_engine_options(&opt.distributed, &opt,\n                                        prep_err, sizeof(prep_err)) != 0) {\n        fprintf(stderr, \"ds4-worker: %s\\n\", prep_err);\n        return 2;\n    }\n\n    ds4_engine *engine = NULL;\n    if (ds4_engine_open(&engine, &opt) != 0 || !engine) {\n        fprintf(stderr, \"ds4-worker: failed to open engine\\n\");\n        return 1;\n    }\n\n    ds4_dist_generation_options gen = {0};\n    gen.ctx_size = ctx_size;\n    int rc = ds4_dist_run(engine, &opt.distributed, &gen);\n    ds4_engine_close(engine);\n    return rc;\n}\n","sourceCodeStart":99,"sourceCodeEnd":127,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/cpp/ds4/worker_main.c#L99-L127","documentation":"Runtime failure opening the ds4 engine: ds4_engine_open() returned non-zero or produced a NULL engine, so the worker prints this and exits 1 (a runtime failure, distinct from the usage-error exit 2). Root causes are model-file problems (missing, corrupt, wrong GGUF) or a backend/hardware mismatch such as requesting CUDA on a GPU-less node.","triggerScenarios":"Running ds4-worker with a truncated/invalid GGUF path contents, with --cuda on a machine without a CUDA device or driver, or with --metal off Apple Silicon; ds4_engine_open logs its own detail first, then this line summarizes and the process exits.","commonSituations":"Containers without GPU device passthrough; models incompletely downloaded; driver/CUDA toolkit mismatch; wrong default backend for the platform (default_backend() picks CUDA on non-Apple Linux).","solutions":["Scroll to the ds4_engine_open diagnostic just above this line — it states file vs device specifics; fix that first.","Verify the model: file exists, size matches upstream, and passes a GGUF sanity check (re-download if suspect).","Match the backend flag to hardware: --cpu on CPU-only nodes, --cuda with a working nvidia-smi inside the container, --metal on Apple Silicon.","Re-run with the corrected flag/path; exit code 1 here is environmental, not argument usage."],"exampleFix":"# before (GPU-less node)\nds4-worker --role worker --cuda -m /m.gguf   # failed to open engine\n\n# after\nds4-worker --role worker --cpu -m /m.gguf","handlingStrategy":"validation","validationCode":"# pre-flight: model readable and backend matches hardware\n[ -f \"$MODEL\" ] || { echo \"model missing: $MODEL\" >&2; exit 1; }\nBACKEND=--cpu\ncommand -v nvidia-smi >/dev/null && nvidia-smi >/dev/null 2>&1 && BACKEND=--cuda\n[[ $(uname -s) == Darwin ]] && BACKEND=--metal\nexec ds4-worker --role worker $BACKEND -m \"$MODEL\" \"$@\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify model integrity (size/checksum against the gallery) before first launch.","Confirm device visibility inside containers (nvidia-smi, /dev/dri, Metal on macOS) before choosing --cuda/--metal.","Treat exit code 1 from ds4-worker as environmental: inspect the ds4_engine_open log line, fix, relaunch."],"tags":["c","ds4","engine","model-loading","hardware"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}