{"record":{"id":"58ad473ca0bb7be9","repo":"xai-org/x-algorithm","slug":"head-names-unknown-are-not-in-head-order-refus","errorCode":null,"errorMessage":"head names {unknown} are not in HEAD_ORDER — refusing to start","messagePattern":"head names (.+?) are not in HEAD_ORDER — refusing to start","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"bdsm/runtime/gpu_scorer.py","lineNumber":78,"sourceCode":"            f\"backbone hash mismatch: file={actual} manifest={manifest.get('file_sha256')} \"\n            f\"pinned={PINNED_BACKBONE_SHA256} — refusing to start\"\n        )\n\n    with open(os.path.join(args.head_checkpoint, \"config.json\")) as f:\n        head_cfg = json.load(f)\n    if head_cfg.get(\"head_registry_hash\") != PINNED_HEAD_REGISTRY_HASH:\n        raise RuntimeError(\n            f\"head registry hash {head_cfg.get('head_registry_hash')} != \"\n            f\"{PINNED_HEAD_REGISTRY_HASH} — refusing to start\"\n        )\n    if head_cfg.get(\"backbone_sha256\") != PINNED_BACKBONE_SHA256:\n        raise RuntimeError(\n            \"head checkpoint was trained against a different backbone — refusing to start\"\n        )\n    head_names = list(head_cfg[\"head_names\"])\n    unknown = [n for n in head_names if n not in HEAD_ORDER]\n    if unknown:\n        raise RuntimeError(f\"head names {unknown} are not in HEAD_ORDER — refusing to start\")\n    log.info(\n        f\"weights pinned OK: backbone sha {actual[:8]}…, \"\n        f\"head registry {PINNED_HEAD_REGISTRY_HASH}, heads {head_names}\"\n    )\n    return manifest, head_cfg, head_names\n\n\ndef _start_health_server(port: int, metrics: dict, config_view: dict):\n    class H(BaseHTTPRequestHandler):\n        def do_GET(self):\n            if self.path.rstrip(\"/\") == \"/config\":\n                body = json.dumps(config_view, indent=2).encode()\n            else:\n                body = \"\".join(f\"{k}={v}\\n\" for k, v in sorted(metrics.items())).encode()\n            self.send_response(200)\n            self.send_header(\"Content-Type\", \"text/plain\")\n            self.end_headers()\n            self.wfile.write(body)","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/bdsm/runtime/gpu_scorer.py#L60-L96","documentation":"After hash checks, the scorer validates that every name in the checkpoint's head_names list exists in the compiled-in HEAD_ORDER. Unknown names mean the checkpoint ships heads the serving code cannot route, so startup aborts.","triggerScenarios":"A checkpoint containing a newly added head while the scorer binary's HEAD_ORDER predates it; renamed heads between releases; hand-crafted checkpoint with ad-hoc head names.","commonSituations":"Head added to training config but serving binary not bumped; branch artifacts mixed; typo in head naming during export.","solutions":["Diff config.json head_names against HEAD_ORDER in the deployed scorer","Upgrade the scorer binary to a version whose HEAD_ORDER includes the new head(s)","Or re-export the checkpoint without the unknown head","Keep head registry, HEAD_ORDER, and checkpoints versioned in one release unit"],"exampleFix":"# HEAD_ORDER must contain every entry of config.json head_names:\njq .head_names /ckpt/config.json","handlingStrategy":"validation","validationCode":"cfg = json.load(open(f\"{args.head_checkpoint}/config.json\"))\nunknown = [n for n in cfg['head_names'] if n not in HEAD_ORDER]\nassert not unknown, unknown","typeGuard":"def heads_supported(names: list) -> bool:\n    return all(n in HEAD_ORDER for n in names)","tryCatchPattern":"try:\n    _verify_pinned_weights(args)\nexcept RuntimeError as e:\n    if 'not in HEAD_ORDER' in str(e):\n        upgrade_scorer_or_reexport()\n    raise","preventionTips":["Update HEAD_ORDER and head registry atomically with head additions","Validate exported checkpoints in CI against the serving HEAD_ORDER","Keep head names in a single shared constant module"],"tags":["python","model-integrity","head-routing","validation"],"backgroundTag":"artifact-checksum-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}