{"record":{"id":"b7d5120e46f98399","repo":"Comfy-Org/ComfyUI","slug":"this-controlnet-needs-a-vae-but-none-was-provided","errorCode":null,"errorMessage":"This Controlnet needs a VAE but none was provided, please use a ControlNetApply node with a VAE input and connect it.","messagePattern":"This Controlnet needs a VAE but none was provided, please use a ControlNetApply node with a VAE input and connect it\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy/controlnet.py","lineNumber":278,"sourceCode":"                if control_prev is not None:\n                    return control_prev\n                else:\n                    return None\n\n        dtype = self.control_model.dtype\n        if self.manual_cast_dtype is not None:\n            dtype = self.manual_cast_dtype\n\n        if self.cond_hint is None or x_noisy.shape[2] * self.compression_ratio != self.cond_hint.shape[2] or x_noisy.shape[3] * self.compression_ratio != self.cond_hint.shape[3]:\n            if self.cond_hint is not None:\n                del self.cond_hint\n            self.cond_hint = None\n            compression_ratio = self.compression_ratio\n            if self.vae is not None:\n                compression_ratio *= self.vae.spacial_compression_encode()\n            else:\n                if self.latent_format is not None:\n                    raise ValueError(\"This Controlnet needs a VAE but none was provided, please use a ControlNetApply node with a VAE input and connect it.\")\n            self.cond_hint = comfy.utils.common_upscale(self.cond_hint_original, x_noisy.shape[-1] * compression_ratio, x_noisy.shape[-2] * compression_ratio, self.upscale_algorithm, \"center\")\n            self.cond_hint = self.preprocess_image(self.cond_hint)\n            if self.vae is not None:\n                loaded_models = comfy.model_management.loaded_models(only_currently_used=True)\n                self.cond_hint = self.vae.encode(self.cond_hint.movedim(1, -1))\n                comfy.model_management.load_models_gpu(loaded_models)\n            if self.latent_format is not None:\n                self.cond_hint = self.latent_format.process_in(self.cond_hint)\n            if len(self.extra_concat_orig) > 0:\n                to_concat = []\n                for c in self.extra_concat_orig:\n                    c = c.to(self.cond_hint.device)\n                    c = comfy.utils.common_upscale(c, self.cond_hint.shape[-1], self.cond_hint.shape[-2], self.upscale_algorithm, \"center\")\n                    if c.ndim < self.cond_hint.ndim:\n                        c = c.unsqueeze(2)\n                        c = comfy.utils.repeat_to_batch_size(c, self.cond_hint.shape[2], dim=2)\n                    to_concat.append(comfy.utils.repeat_to_batch_size(c, self.cond_hint.shape[0]))\n                self.cond_hint = torch.cat([self.cond_hint] + to_concat, dim=1)","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy/controlnet.py#L260-L296","documentation":"ControlNet raises this when the loaded controlnet operates in latent space (latent_format is not None, e.g. controlnets that consume VAE-encoded hints like those for Flux/SD3-style latents) but no VAE was wired into the ControlNetApply node. Without the VAE, compression cannot be computed and the hint cannot be encoded, so the error tells you to connect the VAE input.","triggerScenarios":"Using ControlNetApply (or ControlNetApplyAdvanced) without linking the positive/negative VAE input while the controlnet model requires latent hints (latent_format set at load time); swapping a pixel-space controlnet for a latent-space one in an existing workflow without adding the VAE link.","commonSituations":"Newer latent-hint controlnet models dropped into old workflows; converting a workflow that previously didn't need the VAE connection; forgetting that some apply nodes have an optional-but-required-here VAE socket.","solutions":["Open the ControlNetApply node and connect the workflow's VAE to its VAE input.","Use ControlNetApplyAdvanced with the VAE input connected for latent-space controlnets.","If the workflow should stay pixel-space, load the pixel-space variant of the controlnet instead."],"exampleFix":"# workflow (dict) before: apply node missing vae link\n{\"class_type\": \"ControlNetApplyAdvanced\", \"inputs\": {\"positive\": [...], \"negative\": [...], \"control_net\": [...]}}\n\n# after: add vae input\n{\"class_type\": \"ControlNetApplyAdvanced\", \"inputs\": {\"positive\": [...], \"negative\": [...], \"control_net\": [...], \"vae\": [\"4\", 0]}}","handlingStrategy":"validation","validationCode":"if controlnet.latent_format is not None and vae is None:\n    raise SystemExit(\"connect the VAE input of ControlNetApply for this controlnet\")","typeGuard":"def controlnet_needs_vae(controlnet) -> bool:\n    return getattr(controlnet, \"latent_format\", None) is not None","tryCatchPattern":"try:\n    cn.apply_model(...)\nexcept ValueError as e:\n    if \"needs a VAE\" in str(e):\n        raise SystemExit(\"wire the VAE into the ControlNetApply node\")\n    raise","preventionTips":["Always connect the VAE socket when using latent-space controlnets.","Check controlnet.latent_format when swapping controlnet models in workflows."],"tags":["controlnet","vae","workflow"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}