windmill-labs/windmill · error

worker name '{name}' is {} characters, more than the {MAX_WO

Error message

worker name '{name}' is {} characters, more than the {MAX_WORKER_NAME_LEN} a worker name may have: shorten WORKER_GROUP or WORKER_SUFFIX

What it means

`checked_worker_name` composes the final worker name (agent/worker group + suffix) and enforces MAX_WORKER_NAME_LEN. The name is stored in a VARCHAR(255) primary key, so a longer name would fail at DB insert time in a confusing way; Windmill refuses it upfront with a message telling the operator exactly which knobs to shorten. Called when constructing WorkerConn at worker startup.

Source

Thrown at backend/windmill-common/src/utils.rs:455

    if is_agent {
        format!("{}-{}-{}", AGENT_WORKER_NAME_PREFIX, worker_group, suffix)
    } else {
        format!("{}-{}-{}", WORKER_NAME_PREFIX, worker_group, suffix)
    }
}

/// The name is the `VARCHAR(255)` primary key of `worker_ping` and a component of the worker
/// directory's path, and every part of it comes from the environment (`WORKER_GROUP`,
/// hostname, `WORKER_SUFFIX`). A name that does not fit has to stop the process here rather
/// than at the directory it creates or the initial ping it `expect`s.
pub fn checked_worker_name(
    is_agent: bool,
    worker_group: &str,
    suffix: &str,
) -> anyhow::Result<String> {
    let name = worker_name_with_suffix(is_agent, worker_group, suffix);
    if name.len() > MAX_WORKER_NAME_LEN {
        return Err(anyhow::anyhow!(
            "worker name '{name}' is {} characters, more than the {MAX_WORKER_NAME_LEN} a worker \
            name may have: shorten WORKER_GROUP or WORKER_SUFFIX",
            name.len()
        ));
    }
    Ok(name)
}

pub fn retrieve_common_worker_prefix(worker_name: &str) -> String {
    let (prefix, _) = worker_name.rsplit_once('-').unzip();

    prefix
        .expect("Invalid worker_name: expected at least one '-' in the name")
        .to_owned()
}

pub fn paginate(pagination: Pagination) -> (usize, usize) {
    let per_page = pagination

View on GitHub (pinned to e474e8803c)

Solutions

1. Shorten WORKER_GROUP and/or WORKER_SUFFIX until the composed name is ≤ MAX_WORKER_NAME_LEN (255) characters, as the error message advises.
2. Move descriptive metadata (region, team, hardware) out of the name into worker tags or labels used for routing instead.
3. Automate the guard: in your deployment manifest, assert `len(group) + len(suffix) + 1 <= 255` before rollout.
4. If the name is derived from a pod hostname, truncate or hash the variable part.

Example fix

// before (helm values)
workerGroup: eu-west-1-production-heavy-duty-eds-processing
workerSuffix: workers_pool_a_2026
// after
workerGroup: eu1_prod_hv
workerSuffix: pool_a

const MAX_WORKER_NAME_LEN = 255;
const name = `${agentPrefix ?? ""}${workerGroup}_${suffix}`;
if (name.length > MAX_WORKER_NAME_LEN) {
  throw new Error(`worker name '${name}' is ${name.length} chars; shorten WORKER_GROUP or WORKER_SUFFIX`);
}

try {
  connectWorker({ group: workerGroup, suffix });
} catch (e) {
  if (String(e).includes("more than the")) {
    console.error("Worker name exceeds VARCHAR(255); shorten WORKER_GROUP/WORKER_SUFFIX or move metadata to tags.");
  }
  throw e;
}

When it happens

Trigger: Starting a worker whose combined WORKER_GROUP + '_' + WORKER_SUFFIX (+ any agent prefix) exceeds MAX_WORKER_NAME_LEN (255) characters; the check fires in `checked_worker_name` before the worker pings the server.

Common situations: Long k8s StatefulSet/pod-derived group names combined with a long WORKER_SUFFIX; users attempting to encode region, environment, team and hardware details all into worker naming; suffix validation passing (952) but the group being very long.

Related errors

• 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
• Failed to initialize oracle client: {e}
• ${what} failed:\n${output}

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