{"record":{"id":"cc9cff4d3f5aaa34","repo":"xai-org/x-algorithm","slug":"xai-user-environment-variable-is-required","errorCode":null,"errorMessage":"XAI_USER environment variable is required","messagePattern":"XAI_USER environment variable is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/configs/data_feeds.py","lineNumber":86,"sourceCode":"}\n\n\ndef _off_cluster_suffix() -> str:\n    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","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/configs/data_feeds.py#L68-L104","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["export XAI_USER=<your-username> (or add it to your launch script/Dockerfile/env file)","If running fully off-cluster, unset all three XAI_* variables so the off-cluster fallback suffix is used instead","Audit the deployment env to ensure XAI_USER, XAI_JOB_NAME, and XAI_CLUSTER are set together"],"exampleFix":"# before\n$ python train.py --config recs_v2  # XAI_JOB_NAME set, XAI_USER missing\n\n# after\n$ export XAI_USER=alice\n$ python train.py --config recs_v2","handlingStrategy":"validation","validationCode":"import os\n\ndef validate_job_env() -> None:\n    present = [v for v in (\"XAI_USER\", \"XAI_JOB_NAME\", \"XAI_CLUSTER\") if os.getenv(v)]\n    if present and not os.getenv(\"XAI_USER\"):\n        raise SystemExit(\"XAI_USER required when other XAI_* vars are set\")","typeGuard":"null","tryCatchPattern":"try:\n    suffix = job_suffix()\nexcept ValueError as e:\n    if \"XAI_USER\" in str(e):\n        raise SystemExit(\"Set XAI_USER (or unset all XAI_* vars for off-cluster runs)\") from e\n    raise","preventionTips":["Export all three XAI_* identity vars together from one launcher script","For off-cluster dev, explicitly unset all three so the fallback suffix is used","Add an env sanity check at job entry before any Kafka consumer is built"],"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"}