windmill-labs/windmill · error

Worker instance and version are required

Error message

Worker instance and version are required

What it means

When a worker sends a PingType::Initial ping, the backend requires the ping payload to carry the worker_instance and version fields, because the initial ping is what registers the worker and its running version in the database. If either is missing, insert_ping_query cannot be called safely, so the API rejects the ping with this error.

Source

Thrown at backend/windmill-common/src/worker.rs:1781

                insert_ping.tags.unwrap_or_default().as_slice(),
                insert_ping.vcpus,
                insert_ping.memory,
                insert_ping.jobs_executed,
                insert_ping.occupancy_rate,
                insert_ping.memory_usage,
                insert_ping.wm_memory_usage,
                insert_ping.occupancy_rate_15s,
                insert_ping.occupancy_rate_5m,
                insert_ping.occupancy_rate_30m,
                insert_ping.native_mode.unwrap_or(false),
                insert_ping.ip.as_deref(),
                db,
            )
            .await?
        }
        PingType::Initial => {
            if insert_ping.worker_instance.is_none() || insert_ping.version.is_none() {
                return Err(anyhow::anyhow!("Worker instance and version are required"));
            }

            insert_ping_query(
                &insert_ping.worker_instance.unwrap(),
                &worker_name,
                worker_group,
                // An agent worker sends the sentinel rather than nothing, to stay acceptable to
                // servers that still require an IP here; both mean "not resolved yet".
                insert_ping.ip.as_deref().filter(|ip| *ip != UNKNOWN_IP),
                insert_ping.tags.unwrap_or_default().as_slice(),
                insert_ping.dw,
                insert_ping.dws.as_deref(),
                &insert_ping.version.unwrap(),
                insert_ping.vcpus,
                insert_ping.memory,
                insert_ping.job_isolation,
                insert_ping.native_mode.unwrap_or(false),
                db,

View on GitHub (pinned to e474e8803c)

Solutions

1. Ensure the ping payload includes both worker_instance and version for PingType::Initial
2. Upgrade the worker binary to match the server version so it populates these fields automatically
3. If calling the API directly (e.g. in tests or scripts), set worker_instance to the worker's identifier and version to the worker's semantic version string

Example fix

// before
{"ping_type": "Initial", "worker_name": "w1"}
// after
{"ping_type": "Initial", "worker_name": "w1", "worker_instance": "w1@host-abc", "version": "v1.500.0"}

if ping.ping_type == "Initial" && (ping.worker_instance.is_none() || ping.version.is_none()) {
    return Err("Initial ping requires worker_instance and version");
}

fn has_initial_fields(p: &Ping) -> bool {
    p.ping_type != "Initial" || (p.worker_instance.is_some() && p.version.is_some())
}

match client.send_ping(&ping).await {
    Ok(_) => {},
    Err(e) if e.to_string().contains("Worker instance and version are required") => {
        eprintln!("ping payload incomplete: populate worker_instance and version");
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: A worker (or a custom/third-party client mimicking one) POSTs a worker ping with type 'Initial' but leaves worker_instance or version null — typically a hand-crafted API call, an old worker binary, or a load-test script that builds the ping payload by hand.

Common situations: Running a worker version older than the server that predates the worker_instance/version fields; proxying the workers API through a custom tool that strips fields; automated monitoring scripts that ping the endpoint with incomplete payloads.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ${errorMessage}
• WORKER_SUFFIX must only contain ASCII letters, digits and un
• WORKER_SUFFIX must be at most {MAX_WORKER_SUFFIX_LABEL_LEN}
• EXIT_AFTER_N_JOBS must be a positive integer (or 0 to disabl
• result.substring(__RESULT_ERR_PREFIX.length)

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/16d78f3118cace5b. Report an issue: GitHub.