WORKER_SUFFIX must be at most {MAX_WORKER_SUFFIX_LABEL_LEN}

Error message

WORKER_SUFFIX must be at most {MAX_WORKER_SUFFIX_LABEL_LEN} characters, got {}

What it means

`create_labelled_worker_suffix` enforces a maximum length (MAX_WORKER_SUFFIX_LABEL_LEN) on the WORKER_SUFFIX label. Because the label is embedded into the worker name — a VARCHAR(255) primary key — and into the worker directory path, an over-long label would only surface as a DB or filesystem failure at the first ping. Windmill fails fast with this error instead.

Source

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

/// identity, and it already folds in the worker index. A `-` in the label would add a segment
/// to the worker name, which [`retrieve_common_worker_prefix`] reads as the part to strip;
/// rejected rather than rewritten, since the point of the label is that two different ones
/// give two different names.
fn create_labelled_worker_suffix(
    hostname: &str,
    label: &str,
    index: usize,
) -> anyhow::Result<String> {
    if !label.chars().all(|c| c.is_ascii_alphanumeric() || c == '_') {
        return Err(anyhow::anyhow!(
            "WORKER_SUFFIX must only contain ASCII letters, digits and underscores, got '{label}'"
        ));
    }
    // The worker name is a `VARCHAR(255)` primary key and a component of the worker
    // directory's path: a label long enough to blow either only surfaces at the initial ping,
    // which the worker `expect`s.
    if label.len() > MAX_WORKER_SUFFIX_LABEL_LEN {
        return Err(anyhow::anyhow!(
            "WORKER_SUFFIX must be at most {MAX_WORKER_SUFFIX_LABEL_LEN} characters, got {}",
            label.len()
        ));
    }
    Ok(format!(
        "{}_{label}",
        create_stable_worker_suffix(hostname, index)
    ))
}

pub fn worker_name_with_suffix(is_agent: bool, worker_group: &str, suffix: &str) -> String {
    if is_agent {
        format!("{}-{}-{}", AGENT_WORKER_NAME_PREFIX, worker_group, suffix)
    } else {
        format!("{}-{}-{}", WORKER_NAME_PREFIX, worker_group, suffix)
    }
}

View on GitHub (pinned to e474e8803c)

Solutions

Shorten WORKER_SUFFIX to at most MAX_WORKER_SUFFIX_LABEL_LEN characters.
If the label encodes multiple dimensions, use short codes (e.g. `eu1_hv`) instead of full words.
If uniqueness requires length, shift the extra information into WORKER_GROUP and shorten WORKER_GROUP too so the total worker name fits (see also the worker-name-length error).
Check for accidental content: the value may contain an entire line pasted by mistake — trim it.

Example fix

// before
WORKER_SUFFIX=europe_west_1_heavy_duty_eds_processing_workers_pool
// after
WORKER_SUFFIX=eu1_hv

Defensive patterns

Strategy: validation

Validate before calling

const label = process.env.WORKER_SUFFIX ?? "";
const MAX = 255; // MAX_WORKER_SUFFIX_LABEL_LEN
if (label.length > MAX) {
  throw new Error(`WORKER_SUFFIX is ${label.length} chars; must be at most ${MAX}`);
}

Try / catch

try {
  startWorker({ suffix: process.env.WORKER_SUFFIX });
} catch (e) {
  if (String(e).includes("WORKER_SUFFIX must be at most")) {
    console.error("Shorten WORKER_SUFFIX or move detail into WORKER_GROUP/tags.");
    process.exit(1);
  }
  throw e;
}

Prevention

Keep WORKER_SUFFIX to short codes (≤ ~20 chars) in deployment templates.
Don't concatenate branch names/run IDs/timestamps into WORKER_SUFFIX.
Assert label length in CI before deploying worker manifests.
Check for accidental pasted content when the value looks unusually long.

When it happens

Trigger: Starting a worker with WORKER_SUFFIX set to a string longer than MAX_WORKER_SUFFIX_LABEL_LEN characters; `resolve_worker_suffix` → `create_labelled_worker_suffix` rejects it before the worker registers.

Common situations: Long descriptive labels like `WORKER_SUFFIX=eu_west_1_heavy_duty_eds_processing_workers`; CI-generated suffixes built by concatenating branch names, run IDs and timestamps; accidentally pasting a whole config line into the variable.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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