xai-org/x-algorithm · error · ValueError

XAI_USER environment variable is required

Error message

XAI_USER environment variable is required

What it means

When building Kafka consumer group IDs / job suffixes, job_suffix() reads XAI_USER, XAI_JOB_NAME, and XAI_CLUSTER. If at least one of them is set but XAI_USER is missing, this ValueError fires (if all three are unset it falls back to an off-cluster suffix instead).

Source

Thrown at phoenix/xrex/configs/data_feeds.py:86

}


def _off_cluster_suffix() -> str:
    user = (os.environ.get("USER") or os.environ.get("LOGNAME") or "oss").strip()
    host = (cluster_identity.get_hostname() or socket.gethostname() or "localhost").strip()
    return f"{user}_local_{host}"


def job_suffix() -> str:
    user = cluster_identity.get_user()
    job = cluster_identity.get_job_name()
    cluster = cluster_identity.get_cluster()

    if not (user or job or cluster):
        return _off_cluster_suffix()

    if not user:
        raise ValueError("XAI_USER environment variable is required")
    if not job:
        raise ValueError("XAI_JOB_NAME environment variable is required")
    if not cluster:
        raise ValueError("XAI_CLUSTER environment variable is required")

    return f"{user}_{job}_{cluster}"


def _group_id(config_name: str) -> str:
    return f"{GROUP_IDS[config_name]}_{job_suffix()}"


def resolve_global_ids_file_path(global_ids_file_path: Path | None) -> Path | None:
    if global_ids_file_path == _SID_GLOBAL_IDS_PLACEHOLDER:
        return SID_GLOBAL_IDS_SNAPSHOT
    return global_ids_file_path

View on GitHub (pinned to 24c60942c5)

Solutions

1. export XAI_USER=<your-username> (or add it to your launch script/Dockerfile/env file)
2. If running fully off-cluster, unset all three XAI_* variables so the off-cluster fallback suffix is used instead
3. Audit the deployment env to ensure XAI_USER, XAI_JOB_NAME, and XAI_CLUSTER are set together

Example fix

# before
$ python train.py --config recs_v2  # XAI_JOB_NAME set, XAI_USER missing

# after
$ export XAI_USER=alice
$ python train.py --config recs_v2

import os

def validate_job_env() -> None:
    present = [v for v in ("XAI_USER", "XAI_JOB_NAME", "XAI_CLUSTER") if os.getenv(v)]
    if present and not os.getenv("XAI_USER"):
        raise SystemExit("XAI_USER required when other XAI_* vars are set")

null

try:
    suffix = job_suffix()
except ValueError as e:
    if "XAI_USER" in str(e):
        raise SystemExit("Set XAI_USER (or unset all XAI_* vars for off-cluster runs)") from e
    raise

When it happens

Trigger: Calling job_suffix() (directly or via _group_id / _gen_recs_aggregated_kafka) in an environment where XAI_JOB_NAME and/or XAI_CLUSTER are exported but XAI_USER is not, or XAI_USER is set to an empty string.

Common situations: Running a Kafka-consuming job outside the standard cluster launcher that normally injects these variables; a Docker/k8s manifest that copies only some of the XAI_* vars; XAI_USER exported as empty; CI shells that drop user env vars.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• XAI_JOB_NAME environment variable is required
• XAI_CLUSTER environment variable is required
• BDSM_CHALLENGE_SALT env var is required for challenge routin
• {cls.__name__} must set TASK_GENERATOR_TYPE to be registered
• Duplicate generator registration for {key!r}: {existing.__na

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/cc9cff4d3f5aaa34. Report an issue: GitHub.