{"record":{"id":"833106bfe5075dc4","repo":"666ghj/MiroFish","slug":"unsupported-history-schema-version","errorCode":null,"errorMessage":"unsupported history schema_version","messagePattern":"unsupported history schema_version","errorType":"exception","errorClass":"StarHistoryError","httpStatus":null,"severity":"critical","filePath":"scripts/star_history.py","lineNumber":360,"sourceCode":"\n\ndef validate_state(state: Any) -> None:\n    if not isinstance(state, dict):\n        raise StarHistoryError(\"history state must be a JSON object\")\n    _expect_keys(\n        state,\n        {\n            \"schema_version\",\n            \"repository\",\n            \"timezone\",\n            \"ongoing_interval_days\",\n            \"reconstruction\",\n            \"snapshots\",\n        },\n        \"history state\",\n    )\n    if state[\"schema_version\"] != 1 or type(state[\"schema_version\"]) is not int:\n        raise StarHistoryError(\"unsupported history schema_version\")\n    if state[\"repository\"] != REPOSITORY:\n        raise StarHistoryError(\"history repository does not match configured repository\")\n    if state[\"timezone\"] != \"UTC\":\n        raise StarHistoryError(\"history timezone must be UTC\")\n    if (\n        state[\"ongoing_interval_days\"] != INTERVAL_DAYS\n        or type(state[\"ongoing_interval_days\"]) is not int\n    ):\n        raise StarHistoryError(\n            f\"history interval must be exactly {INTERVAL_DAYS} days\"\n        )\n\n    reconstruction = state[\"reconstruction\"]\n    if not isinstance(reconstruction, dict):\n        raise StarHistoryError(\"reconstruction must be an object\")\n    _expect_keys(\n        reconstruction,\n        {\"method\", \"generated_at\", \"daily\"},","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/scripts/star_history.py#L342-L378","documentation":"validate_state requires schema_version to be exactly int 1 (note the order: != 1 is checked before the type check, so 1.0/True/'1' also fail since True != 1 is False but type(True) is not int — both clauses combine to reject anything that is not a literal int 1). Anything else raises StarHistoryError('unsupported history schema_version'). This is the version gate for the state file format.","triggerScenarios":"State file with schema_version: 2 (written by a newer script), \"1\" (string), 1.0 (float), or true (bool); also missing-schema_version variants are caught earlier by _expect_keys.","commonSituations":"Running an older script version against a state file produced by a newer version; hand-edited version field; a fork that bumped the schema.","solutions":["Update the script to the version that wrote the state file (or downgrade the state by regenerating it)","Discard the state file and let the script perform a full reconstruction","Never hand-edit schema_version — the surrounding structure must match the version"],"exampleFix":"// before (state file)\n\"schema_version\": 2\n\n// after (state file — only if the rest of the file genuinely matches v1)\n\"schema_version\": 1","handlingStrategy":"validation","validationCode":"version = state.get(\"schema_version\")\nif type(version) is not int or version != 1:\n    raise StarHistoryError(f\"state schema_version {version!r} unsupported; this script supports exactly 1\")","typeGuard":"def is_supported_state_version(value: object) -> TypeGuard[int]:\n    return type(value) is int and value == 1","tryCatchPattern":"try:\n    validate_state(state)\nexcept StarHistoryError as exc:\n    if \"unsupported history schema_version\" in str(exc):\n        regenerate_state_file()  # state from another version; rebuild\n    else:\n        raise","preventionTips":["Check schema_version before any other state processing and bail early","After upgrading the script, expect to rebuild or migrate state files — versions are not interchangeable"],"tags":["state-file","schema","versioning","validation","star-history"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}