xai-org/x-algorithm · error · ValueError

XAI_JOB_NAME environment variable is required

Error message

XAI_JOB_NAME environment variable is required

What it means

job_suffix() requires XAI_JOB_NAME when any of the XAI_* identity variables is present. It identifies which job is consuming so unique Kafka group IDs can be formed as {user}_{job}_{cluster}; a missing job name would conflate distinct jobs.

Source

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

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


def _ranking_aggregated_kafka(mparams, hash_table, use_post_sid, sid_num_levels, config_name):
    return PhoenixKafkaDataset(

View on GitHub (pinned to 24c60942c5)

Solutions

1. export XAI_JOB_NAME=<descriptive-job-name> before launching
2. If running fully off-cluster, unset all three XAI_* vars to hit the _off_cluster_suffix() fallback
3. Set the variable in the job spec/launcher so it is provided consistently with XAI_USER and XAI_CLUSTER

Example fix

# before
env | grep XAI
# XAI_USER=alice  XAI_CLUSTER=c1

# after
export XAI_JOB_NAME=recs-nightly
env | grep XAI
# XAI_USER=alice  XAI_JOB_NAME=recs-nightly  XAI_CLUSTER=c1

import os

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

null

try:
    gid = _group_id(config_name)
except ValueError as e:
    if "XAI_JOB_NAME" in str(e):
        raise SystemExit("Set XAI_JOB_NAME to a stable, unique job name") from e
    raise

When it happens

Trigger: Calling job_suffix() (directly or via _group_id / _gen_recs_aggregated_kafka) with XAI_USER and/or XAI_CLUSTER set but XAI_JOB_NAME unset or empty.

Common situations: Ad-hoc local runs where the user exported XAI_USER manually but no job name; a renamed/removed XAI_JOB_NAME in deployment templates; empty-string export overriding a valid value.

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_USER 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/07e533a56ee145ac. Report an issue: GitHub.