{"record":{"id":"e2d37f8d69b58039","repo":"xai-org/x-algorithm","slug":"xai-cluster-environment-variable-is-required","errorCode":null,"errorMessage":"XAI_CLUSTER environment variable is required","messagePattern":"XAI_CLUSTER environment variable is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/configs/data_feeds.py","lineNumber":90,"sourceCode":"    user = (os.environ.get(\"USER\") or os.environ.get(\"LOGNAME\") or \"oss\").strip()\n    host = (cluster_identity.get_hostname() or socket.gethostname() or \"localhost\").strip()\n    return f\"{user}_local_{host}\"\n\n\ndef job_suffix() -> str:\n    user = cluster_identity.get_user()\n    job = cluster_identity.get_job_name()\n    cluster = cluster_identity.get_cluster()\n\n    if not (user or job or cluster):\n        return _off_cluster_suffix()\n\n    if not user:\n        raise ValueError(\"XAI_USER environment variable is required\")\n    if not job:\n        raise ValueError(\"XAI_JOB_NAME environment variable is required\")\n    if not cluster:\n        raise ValueError(\"XAI_CLUSTER environment variable is required\")\n\n    return f\"{user}_{job}_{cluster}\"\n\n\ndef _group_id(config_name: str) -> str:\n    return f\"{GROUP_IDS[config_name]}_{job_suffix()}\"\n\n\ndef resolve_global_ids_file_path(global_ids_file_path: Path | None) -> Path | None:\n    if global_ids_file_path == _SID_GLOBAL_IDS_PLACEHOLDER:\n        return SID_GLOBAL_IDS_SNAPSHOT\n    return global_ids_file_path\n\n\ndef _ranking_aggregated_kafka(mparams, hash_table, use_post_sid, sid_num_levels, config_name):\n    return PhoenixKafkaDataset(\n        **phoenix_kafka_kwargs(),\n        topic_name=settings.RANKING_KAFKA_TOPIC,","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/configs/data_feeds.py#L72-L108","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["export XAI_CLUSTER=<cluster-name> matching the cluster you consume from","For fully local/off-cluster runs, clear all three XAI_* variables to trigger the off-cluster suffix","Fix deployment manifests so all three identity vars are injected as a set"],"exampleFix":"# before\nexport XAI_USER=alice\nexport XAI_JOB_NAME=recs\n# XAI_CLUSTER missing -> ValueError\n\n# after\nexport XAI_USER=alice\nexport XAI_JOB_NAME=recs\nexport XAI_CLUSTER=prod-us-east","handlingStrategy":"validation","validationCode":"import os\n\ndef validate_job_env() -> None:\n    names = (\"XAI_USER\", \"XAI_JOB_NAME\", \"XAI_CLUSTER\")\n    present = [n for n in names if os.getenv(n)]\n    if present and not os.getenv(\"XAI_CLUSTER\"):\n        raise SystemExit(\"XAI_CLUSTER required when other XAI_* vars are set\")","typeGuard":"null","tryCatchPattern":"try:\n    suffix = job_suffix()\nexcept ValueError as e:\n    if \"XAI_CLUSTER\" in str(e):\n        raise SystemExit(\"Set XAI_CLUSTER to the cluster you consume from\") from e\n    raise","preventionTips":["Set XAI_CLUSTER to the exact cluster the Kafka brokers belong to","Treat XAI_USER/XAI_JOB_NAME/XAI_CLUSTER as one unit in deployment manifests","Log os.environ XAI_* values at startup for faster diagnosis"],"tags":["environment-variable","kafka","configuration","python"],"backgroundTag":"missing-env-var","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}