What causes "ds4-worker: --role worker is required " in mudler/LocalAI?

Add '--role worker' to the command line.

ds4-worker: --role worker is required

Error message

ds4-worker: --role worker is required

What it means

Post-parse invariant check in ds4-worker: after argument parsing, opt.distributed.role must equal DS4_DISTRIBUTED_WORKER. The binary is exclusively a worker — it has no driver/coordinator code path — so starting it without '--role worker' (or with a role value that did not set the enum) exits with status 2 before touching the model or network.

Source

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

            opt.model_path = need_arg(&i, argc, argv, arg);
        } else if (!strcmp(arg, "-c") || !strcmp(arg, "--ctx")) {
            ctx_size = parse_int_arg(need_arg(&i, argc, argv, arg), arg);
        } else if (!strcmp(arg, "-t") || !strcmp(arg, "--threads")) {
            opt.n_threads = parse_int_arg(need_arg(&i, argc, argv, arg), arg);
        } else if (!strcmp(arg, "--cpu")) {
            opt.backend = DS4_BACKEND_CPU;
        } else if (!strcmp(arg, "--cuda")) {
            opt.backend = DS4_BACKEND_CUDA;
        } else if (!strcmp(arg, "--metal")) {
            opt.backend = DS4_BACKEND_METAL;
        } else {
            fprintf(stderr, "ds4-worker: unknown option: %s\n", arg);
            return 2;
        }
    }

    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;

View on GitHub (pinned to 44413a9d06)

Solutions

Add '--role worker' to the command line.
Keep one canonical argv per role in your launcher templates (worker vs driver) so the flag cannot be dropped.
Validate with 'ds4-worker --help' that the assembled command parses before deploying.

Example fix

# before
ds4-worker -m /m.gguf --layers 8

# after
ds4-worker --role worker -m /m.gguf --layers 8

Defensive patterns

Strategy: validation

Validate before calling

# launcher invariant: role flag must be present exactly once
case " $* " in *' --role worker '*) : ;; *) echo "ds4-worker requires --role worker" >&2; exit 2;; esac
exec ds4-worker "$@"

Prevention

Template one argv per role (worker/driver) so the flag is baked in, never appended by hand.
Smoke-test the exact worker command in CI so a dropped --role fails the pipeline, not the node.

When it happens

Trigger: Running 'ds4-worker -m model.gguf --layers 8' with no --role flag, or launching it as if it were the standalone server; the role field stays at its zero value which is not DS4_DISTRIBUTED_WORKER.

Common situations: Adapting a single-node command line for distributed runs and forgetting the role; orchestration templates that omit --role; assuming the binary name alone implies the role.

Related errors

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