mudler/LocalAI · critical

ds4-worker: failed to open engine

Error message

ds4-worker: failed to open engine

What it means

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.

Source

Thrown at backend/cpp/ds4/worker_main.c:117

    if (opt.distributed.role != DS4_DISTRIBUTED_WORKER) {
        fprintf(stderr, "ds4-worker: --role worker is required\n");
        return 2;
    }
    if (!opt.model_path) {
        fprintf(stderr, "ds4-worker: --model is required\n");
        return 2;
    }

    char prep_err[256] = {0};
    if (ds4_dist_prepare_engine_options(&opt.distributed, &opt,
                                        prep_err, sizeof(prep_err)) != 0) {
        fprintf(stderr, "ds4-worker: %s\n", prep_err);
        return 2;
    }

    ds4_engine *engine = NULL;
    if (ds4_engine_open(&engine, &opt) != 0 || !engine) {
        fprintf(stderr, "ds4-worker: failed to open engine\n");
        return 1;
    }

    ds4_dist_generation_options gen = {0};
    gen.ctx_size = ctx_size;
    int rc = ds4_dist_run(engine, &opt.distributed, &gen);
    ds4_engine_close(engine);
    return rc;
}

View on GitHub (pinned to 44413a9d06)

Solutions

1. Scroll to the ds4_engine_open diagnostic just above this line — it states file vs device specifics; fix that first.
2. Verify the model: file exists, size matches upstream, and passes a GGUF sanity check (re-download if suspect).
3. Match the backend flag to hardware: --cpu on CPU-only nodes, --cuda with a working nvidia-smi inside the container, --metal on Apple Silicon.
4. Re-run with the corrected flag/path; exit code 1 here is environmental, not argument usage.

Example fix

# before (GPU-less node)
ds4-worker --role worker --cuda -m /m.gguf   # failed to open engine

# after
ds4-worker --role worker --cpu -m /m.gguf

# pre-flight: model readable and backend matches hardware
[ -f "$MODEL" ] || { echo "model missing: $MODEL" >&2; exit 1; }
BACKEND=--cpu
command -v nvidia-smi >/dev/null && nvidia-smi >/dev/null 2>&1 && BACKEND=--cuda
[[ $(uname -s) == Darwin ]] && BACKEND=--metal
exec ds4-worker --role worker $BACKEND -m "$MODEL" "$@"

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• ds4-worker: missing value for %s
• ds4-worker: invalid value for %s: %s
• ds4-worker: %s
• ds4-worker: unknown option: %s
• ds4-worker: --role worker is required

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/909b1079e54d2671. Report an issue: GitHub.