{"record":{"id":"07e533a56ee145ac","repo":"xai-org/x-algorithm","slug":"xai-job-name-environment-variable-is-required","errorCode":null,"errorMessage":"XAI_JOB_NAME environment variable is required","messagePattern":"XAI_JOB_NAME environment variable is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/configs/data_feeds.py","lineNumber":88,"sourceCode":"\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\ndef _ranking_aggregated_kafka(mparams, hash_table, use_post_sid, sid_num_levels, config_name):\n    return PhoenixKafkaDataset(","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/configs/data_feeds.py#L70-L106","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["export XAI_JOB_NAME=<descriptive-job-name> before launching","If running fully off-cluster, unset all three XAI_* vars to hit the _off_cluster_suffix() fallback","Set the variable in the job spec/launcher so it is provided consistently with XAI_USER and XAI_CLUSTER"],"exampleFix":"# before\nenv | grep XAI\n# XAI_USER=alice  XAI_CLUSTER=c1\n\n# after\nexport XAI_JOB_NAME=recs-nightly\nenv | grep XAI\n# XAI_USER=alice  XAI_JOB_NAME=recs-nightly  XAI_CLUSTER=c1","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_JOB_NAME\"):\n        raise SystemExit(\"XAI_JOB_NAME required when other XAI_* vars are set\")","typeGuard":"null","tryCatchPattern":"try:\n    gid = _group_id(config_name)\nexcept ValueError as e:\n    if \"XAI_JOB_NAME\" in str(e):\n        raise SystemExit(\"Set XAI_JOB_NAME to a stable, unique job name\") from e\n    raise","preventionTips":["Use the standard cluster launcher which injects all XAI_* vars","Keep the trio of identity vars in one env file checked into deployment config","Pick job names that are unique per deployment to avoid Kafka group collisions"],"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"}