{"record":{"id":"380c4d4b3eac1669","repo":"Comfy-Org/ComfyUI","slug":"unrecognized-optical-flow-model-format-expected-a","errorCode":null,"errorMessage":"Unrecognized optical flow model format: expected a torchvision RAFT-large state dict with 'feature_encoder.', 'context_encoder.' and 'update_block.' prefixes.","messagePattern":"Unrecognized optical flow model format: expected a torchvision RAFT-large state dict with 'feature_encoder\\.', 'context_encoder\\.' and 'update_block\\.' prefixes\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_void.py","lineNumber":90,"sourceCode":"            ],\n            outputs=[\n                OpticalFlow.Output(),\n            ],\n        )\n\n    @classmethod\n    def execute(cls, model_name) -> io.NodeOutput:\n\n        model_path = folder_paths.get_full_path_or_raise(\"optical_flow\", model_name)\n        sd = comfy.utils.load_torch_file(model_path, safe_load=True)\n\n        has_raft_keys = (\n            any(k.startswith(\"feature_encoder.\") for k in sd)\n            and any(k.startswith(\"context_encoder.\") for k in sd)\n            and any(k.startswith(\"update_block.\") for k in sd)\n        )\n        if not has_raft_keys:\n            raise ValueError(\n                \"Unrecognized optical flow model format: expected a torchvision \"\n                \"RAFT-large state dict with 'feature_encoder.', 'context_encoder.' \"\n                \"and 'update_block.' prefixes.\"\n            )\n\n        model = raft_large(weights=None, progress=False)\n        model.load_state_dict(sd)\n        model.eval().to(torch.float32)\n\n        patcher = comfy.model_patcher.ModelPatcher(\n            model,\n            load_device=comfy.model_management.get_torch_device(),\n            offload_device=comfy.model_management.unet_offload_device(),\n        )\n        return io.NodeOutput(patcher)\n\n\nclass VOIDQuadmaskPreprocess(io.ComfyNode):","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_void.py#L72-L108","documentation":"The optical flow loader expects a torchvision RAFT-large state dict identifiable by the 'feature_encoder.', 'context_encoder.', and 'update_block.' key prefixes. If none of these prefix families are present the file is not a RAFT checkpoint in the expected layout, and loading it into raft_large() would fail opaquely, so it is rejected up front.","triggerScenarios":"Placing a non-RAFT flow model (e.g. FlowNet, SpyNet, or a custom architecture), a RAFT checkpoint saved with a wrapper prefix (e.g. 'model.' prefixed keys), or a corrupted/truncated file into models/optical_flow and selecting it.","commonSituations":"Downloading a RAFT variant whose keys are nested under a module wrapper; converting weights from another framework without stripping prefixes; pointing the node at a miscategorized checkpoint.","solutions":["Download the torchvision raft_large weights (e.g. raft_large_C_T_V2) and place them in models/optical_flow","If keys have a wrapper prefix like 'model.', strip it when saving so top-level keys start with feature_encoder/context_encoder/update_block","Inspect the checkpoint keys with torch.load and list(sd.keys()) to confirm the layout"],"exampleFix":"# fix a wrapper-prefixed checkpoint\nsd = torch.load('flow.pt', map_location='cpu')\nsd = { k[len('model.'):]: v for k, v in sd.items() if k.startswith('model.') }\ntorch.save(sd, 'flow_fixed.pt')","handlingStrategy":"validation","validationCode":"sd = comfy.utils.load_torch_file(path, safe_load=True)\nneed = (\"feature_encoder.\", \"context_encoder.\", \"update_block.\")\nif not all(any(k.startswith(p) for k in sd) for p in need):\n    raise SystemExit(f\"{path} is not a torchvision RAFT-large state dict\")","typeGuard":"def is_raft_large_sd(sd: dict) -> bool:\n    return all(any(k.startswith(p) for k in sd) for p in (\"feature_encoder.\", \"context_encoder.\", \"update_block.\"))","tryCatchPattern":null,"preventionTips":["Only place torchvision raft_large weights in models/optical_flow","Strip wrapper prefixes (e.g. 'model.') when re-exporting flow checkpoints"],"tags":["optical-flow","raft","model-loading","state-dict"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}