mudler/LocalAI · error

ds4-worker: unknown option: %s

Error message

ds4-worker: unknown option: %s

What it means

ds4-worker's argument fallthrough: after -m/-c/-t/--cpu/--cuda/--metal and the distributed parser all decline to match, the token is unknown and the worker prints it and exits 2. This catches misspelled flags and flags belonging to other binaries before any model load.

Source

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

                    dist_err[0] ? dist_err : "invalid distributed option");
            return 2;
        }
        if (dist_parse == DS4_DIST_CLI_MATCHED) continue;

        if (!strcmp(arg, "-m") || !strcmp(arg, "--model")) {
            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;

View on GitHub (pinned to 44413a9d06)

Solutions

1. Correct the flag: -m/--model PATH, -c/--ctx N, -t/--threads N, --cpu|--cuda|--metal, plus the distributed set shown by --help.
2. Run ds4-worker --help to dump the accepted grammar for this build and diff it against your script.
3. Remove flags intended for other processes from the worker's argv (pass them to the right binary instead).

Example fix

# before
ds4-worker --role worker --model-path /m.gguf

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

# whitelist accepted flags in the launcher
ALLOW='-m --model -c --ctx -t --threads --cpu --cuda --metal --role --layers'
for a in "$@"; do case " $ALLOW " in *" $a "*) ;; *) echo "unknown option: $a" >&2; exit 2;; esac; done

When it happens

Trigger: 'ds4-worker --model-path x.gguf' (should be --model), '--thread 8' (should be --threads), or passing launcher/orchestrator flags like --master to a build whose distributed parser does not know them.

Common situations: Copy-pasting flags from the main ds4 server or a different backend; long/short confusion (-model vs -m); flag renamed between versions.

Related errors

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

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