{"record":{"id":"16f451363e90b4ce","repo":"xai-org/x-algorithm","slug":"head-registry-hash-head-cfg-get-head-registry-ha","errorCode":null,"errorMessage":"head registry hash {head_cfg.get('head_registry_hash')} != {PINNED_HEAD_REGISTRY_HASH} — refusing to start","messagePattern":"head registry hash (.+?) != (.+?) — refusing to start","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"bdsm/runtime/gpu_scorer.py","lineNumber":67,"sourceCode":"    return p.parse_args()\n\n\ndef _verify_pinned_weights(args) -> tuple[dict, dict, list[str]]:\n    manifest_path = os.path.join(args.backbone_dir, \"MANIFEST.json\")\n    with open(manifest_path) as f:\n        manifest = json.load(f)\n    npz_path = os.path.join(args.backbone_dir, \"backbone.npz\")\n    actual = _file_sha256(npz_path)\n    if actual != PINNED_BACKBONE_SHA256 or manifest.get(\"file_sha256\") != PINNED_BACKBONE_SHA256:\n        raise RuntimeError(\n            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","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/bdsm/runtime/gpu_scorer.py#L49-L85","documentation":"The head checkpoint's config.json records head_registry_hash, the identity of the head registry it was trained with. The scorer requires it to equal PINNED_HEAD_REGISTRY_HASH so head-name-to-index mappings cannot drift between training and serving.","triggerScenarios":"Starting the scorer with a head checkpoint trained against an older/newer head registry while the binary pins a different PINNED_HEAD_REGISTRY_HASH; mixing artifacts from two releases; head registry changed (heads added/renamed) without retraining/re-exporting the checkpoint.","commonSituations":"Deploying a new head checkpoint built from a different branch; registry schema change making old checkpoints incompatible; partial rollout where only one of binary or checkpoint was updated.","solutions":["Read head_registry_hash from head_checkpoint/config.json and compare with PINNED_HEAD_REGISTRY_HASH in the deployed code","Deploy binary and head checkpoint from the same release bundle","If the registry legitimately changed, retrain/re-export checkpoints and update the pin together","Audit for mixed-version artifacts on the host (stale dirs, wrong --head_checkpoint flag)"],"exampleFix":"# ensure the checkpoint matches the binary's pin:\njq .head_registry_hash /ckpt/config.json  # must equal PINNED_HEAD_REGISTRY_HASH","handlingStrategy":"validation","validationCode":"cfg = json.load(open(f\"{args.head_checkpoint}/config.json\"))\nassert cfg.get('head_registry_hash') == PINNED_HEAD_REGISTRY_HASH","typeGuard":null,"tryCatchPattern":"try:\n    _verify_pinned_weights(args)\nexcept RuntimeError as e:\n    if 'head registry hash' in str(e):\n        rollback_to_matching_release()\n    raise","preventionTips":["Version head registry, checkpoints, and binary together in one release","Add CI that cross-checks release artifact hashes before publish","Never mix checkpoint dirs across releases"],"tags":["python","model-integrity","checkpoint","registry"],"backgroundTag":"artifact-checksum-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}