xai-org/x-algorithm · error · ValueError

XAI_CLUSTER environment variable is required

Error message

XAI_CLUSTER environment variable is required

What it means

job_suffix() requires XAI_CLUSTER when other XAI_* identity variables are set, so Kafka group IDs include the cluster name and consumers on different clusters don't share offsets. Missing it while XAI_USER/XAI_JOB_NAME exist raises this error.

Source

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

    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(
        **phoenix_kafka_kwargs(),
        topic_name=settings.RANKING_KAFKA_TOPIC,

View on GitHub (pinned to 24c60942c5)

Solutions

1. export XAI_CLUSTER=<cluster-name> matching the cluster you consume from
2. For fully local/off-cluster runs, clear all three XAI_* variables to trigger the off-cluster suffix
3. Fix deployment manifests so all three identity vars are injected as a set

Example fix

# before
export XAI_USER=alice
export XAI_JOB_NAME=recs
# XAI_CLUSTER missing -> ValueError

# after
export XAI_USER=alice
export XAI_JOB_NAME=recs
export XAI_CLUSTER=prod-us-east

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_CLUSTER"):
        raise SystemExit("XAI_CLUSTER required when other XAI_* vars are set")

null

try:
    suffix = job_suffix()
except ValueError as e:
    if "XAI_CLUSTER" in str(e):
        raise SystemExit("Set XAI_CLUSTER to the cluster you consume from") 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_JOB_NAME set but XAI_CLUSTER unset or empty.

Common situations: Running against a dev/bypass Kafka endpoint without setting the cluster var; porting a launcher script that only forwards USER and JOB_NAME; empty-string export from a templated manifest.

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_JOB_NAME 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/e2d37f8d69b58039. Report an issue: GitHub.