The ComfyUI Desktop launcher can fail before the interface ever appears, flashing two vague messages that send new users straight to the forums: “Unable to start ComfyUI Desktop” on the splash window, and a second popup reading “Python process exited with code 1 and signal null” (sometimes rendered as an “Unhandled exception during server start” in the log file). Neither message tells you what is actually wrong, which is why this one error string recurs across Windows, macOS, and Linux installs and across versions from v0.4.x through v0.8.x.

“Code 1” is not a specific fault. It is the Electron shell’s blunt way of reporting that the bundled Python backend failed during boot, for any of several unrelated reasons. This article walks through the concrete root causes that have actually been confirmed by ComfyUI maintainers and community troubleshooting, in the order you should check them. Nothing here is speculative performance data or a fabricated test run; every fix below maps to a documented error message you can see with your own eyes in the app’s log files.

Where the Real Error Hides: Read the Log, Not the Popup

The single highest-value habit in ComfyUI troubleshooting is to stop trusting the popup and go find the log. The popup strips away the one line that matters. ComfyUI Desktop writes two logs that almost always contain the actual traceback:

• main.log — the Electron/launcher log, which includes the Python process exited with code 1 line and the surrounding Unhandled exception during server start context.
• comfyui.log — the Python backend’s own output, where a missing module, a failed import, or a CUDA error will show the real exception and stack trace.

On Windows these live under C:\Users\<YourUser>\AppData\Roaming\ComfyUI\logs\. On macOS, look in ~/Library/Application Support/ComfyUI/logs/. The Desktop app’s built-in Maintenance page also exposes a Console Logs tab that streams the same output in real time while a reinstall or repair is running — often easier to read than the raw files.

When you ask for help on the official ComfyUI forum or in a GitHub issue, paste the last 20–30 lines of comfyui.log. The maintainers can identify the root cause from that log alone in most cases; without it, everyone is guessing. This is the trick that shortcuts days of trial and error.

Root Cause 1: A Missing or Corrupt extra_models_config.yaml

This is the most commonly reported single fix and, importantly, one the ComfyUI team has acknowledged and patched. The telltale line in the log reads something like:

Error invoking remote method 'reinstall': Error: ENOENT: no such file or directory,
lstat 'C:\Users\<User>\AppData\Roaming\ComfyUI\extra_models_config.yaml'

The root cause is usually an interrupted or partially-completed installation, or a previous version that left the config directory in an inconsistent state. When the file extra_models_config.yaml is missing entirely, the launcher’s reinstall path chokes on the lstat call before it can finish setting up the backend.

The fix is a two-minute manual recovery: create the missing file with the minimum valid content and restart the app.

1. Open the folder C:\Users\<YourUser>\AppData\Roaming\ComfyUI\ in File Explorer.
2. Create a new text file named exactly extra_models_config.yaml.
3. Open it in Notepad and type two curly braces on one line — {} — and nothing else.
4. Save, close, and restart ComfyUI Desktop.

If the file exists but appears truncated or empty in a way that breaks the YAML parser, delete it and recreate it with the same {} content. This file holds additional model-path overrides; an empty mapping is a perfectly valid starting state and removes the crash without losing any real configuration.

Root Cause 2: A Corrupt config.json Stuck in a Bad State

A second, closely related failure is a corrupt config.json in the same AppData\Roaming\ComfyUI directory. This is distinct from the YAML issue: the file exists, so there is no ENOENT error, but its contents are malformed or reference paths from a version you have since uninstalled, and the backend dies quietly during startup.

A ComfyUI maintainer recommended a simple workaround while a proper fix was in progress: delete C:\Users\<YourUser>\AppData\Roaming\ComfyUI\config.json and let the next launch regenerate it from defaults. This is safe because the file is a settings cache, not your models or workflows. After deletion, ComfyUI will rebuild it with default values, and you can reconfigure any preferences you had changed.

If you want to be more cautious, rename the file to config.json.bak instead of deleting it, then restart. If the app comes up cleanly, delete the backup. If it does not, you have lost nothing and can restore it.

Root Cause 3: PyTorch Cannot See the GPU (Missing CUDA / Driver)

Sometimes the log points not at a config file but at a deep import or initialization failure. A recurring pattern in the forum threads is a user who had a working install, uninstalled it, then reinstalled — only to hit code 1 on every subsequent launch because PyTorch no longer detects the NVIDIA GPU.

In those cases the useful diagnostic is to look for a line about CUDA being unavailable, or for the backend falling back to CPU-only, followed by a crash. The fix is to ensure the GPU half of the stack is healthy before blaming ComfyUI:

• Confirm your NVIDIA driver is installed and current. A driver that was removed or left half-installed during the uninstall cycle will produce exactly this class of failure even though the GPU is physically present.
• On a Windows portable/standalone install, the bundled launcher scripts such as run_nvidia_gpu.bat exist specifically to boot with the correct CUDA-enabled PyTorch. If you were previously using that script and are now double-clicking the app directly, go back to the GPU-specific launcher.
• Verify PyTorch sees the GPU from Python before launching the full app:
  python -c "import torch; print(torch.cuda.is_available())"
  If this prints False, the problem is the PyTorch/CUDA installation, not ComfyUI.

AMD and Intel Arc users hit a parallel version of this: the correct vendor driver must be installed, and the correct PyTorch build (for example the ROCm or the Intel XPU build) must be matched to it. See the official ComfyUI troubleshooting guide for the vendor-specific driver steps.

We cover the launch-time GPU and memory flags that interact with this in more detail in our walkthrough of the ComfyUI VRAM launch flags, which is worth a read once the app actually boots — the flags there change how aggressively ComfyUI holds weights in VRAM.

Root Cause 4: Leftover Folders from an Interrupted Uninstall

When an install is interrupted mid-way — or when a user uninstalls and reinstalls — stale folders can survive the cleanup and poison the fresh install. A solution that multiple users confirmed in the forum is a full manual wipe of the ComfyUI state directories before reinstalling:

• C:\Users\<YourUser>\AppData\Roaming\ComfyUI
• C:\Users\<YourUser>\AppData\Local\Programs\@comfyorgcomfyui-electron (or the equivalent electron app data folder)
• C:\Users\<YourUser>\Documents\ComfyUI

Deleting these does not remove any models you have downloaded — those live in your models directory, which is deliberately kept separate from the application state. What it removes is cached settings, half-written config files, and stray electron state that a new installer will regenerate cleanly.

One practical caution from the forum: avoid running the portable/standalone install out of your Downloads folder. Windows permission handling on that folder occasionally interferes with the installer or the backend writing files, which can masquerade as a code-1 crash. Move the extracted folder to a path like C:\ComfyUI before launching.

A Reliable Recovery Order, Step by Step

Rather than jumping between fixes, work through them in this order — it goes from least destructive to most, so you preserve your setup wherever possible:

1. Read comfyui.log first. The traceback will usually name which root cause applies, so you can skip straight to the right fix.
2. Repair the config files. Create or recreate extra_models_config.yaml with {}, and rename config.json to config.json.bak. Restart and observe.
3. Check the GPU stack. Confirm the driver is installed and torch.cuda.is_available() returns True. Use the vendor-specific launcher script for your GPU.
4. Use the Maintenance page. The Desktop app’s built-in recovery tool can rebuild the Python virtual environment (Reinstall ComfyUI) or reinstall PyTorch and core packages (Install Python Packages) without wiping your models.
5. Wipe the state folders. If a previous install was interrupted, delete or move the three AppData/Documents directories listed above, then reinstall from scratch.

Each step is independently reproducible, and each maps to a documented symptom — there is no guessing stage here. If you have reached the end of the list and ComfyUI still fails with code 1, you now have a clean, complete comfyui.log to share with the maintainers, which turns a vague forum post into a fast diagnosis.

What “Code 1” Is Not

It is worth being precise about what this error does not tell you, because misreading it wastes time. “Python process exited with code 1 and signal null” is not a Python version problem by itself, it is not a missing-model problem, and it is not evidence that your GPU is incompatible. It is the launcher reporting that a child process exited with a non-zero status while producing no OS-level kill signal. The actual reason lives one level deeper, in the log file. Treat the popup as a pointer to the log, and the log as the source of truth.

Similarly, “signal null” is not a signal at all — it means the process returned an exit code without being terminated by a signal (like a segfault would show). A real segfault or a CUDA OOM crash will display differently, so if you see an in-browser error or a mid-run crash instead, that is a separate class of problem: see our note on memory pressure in the Wan2.2 Animate 14B on 16GB VRAM walkthrough for the VRAM-specific side.

Conclusion

The ComfyUI Desktop “Python process exited with code 1” error is scary precisely because it is generic, but it is also one of the most solvable failures in the ecosystem once you know that the real cause is always a few lines further down in comfyui.log. The three most common culprits — a missing extra_models_config.yaml, a corrupt config.json, and a missing or mismatched CUDA driver — are each fixable in a few minutes with no data loss, and a clean state-folder wipe resolves the leftover cases from interrupted installs.

Start with the log, then repair config files, then verify the GPU stack, and only escalate to the Maintenance page or a full reinstall if those fail. In the large majority of cases you will be back to generating images without ever having to touch your models or workflows.

You upgraded ComfyUI, fired up the same Wan 2.2 or GGUF workflow that ran beautifully yesterday, and something is off. The generation completes, but it feels slower. Worse, when you glance at nvidia-smi, your GPU is sitting at 7–9 GB of VRAM on a 16 GB card, where it used to sit at 13–14 GB. The model fits, but ComfyUI won’t actually use the headroom you paid for.

This is not your imagination, and it is not a corrupted install. It is the fallout from a deliberate change in how ComfyUI core handles model offloading — and it caught a lot of people off guard. This guide walks through the symptom, the root cause, how to confirm it on your own machine, and the launch flags that give you back manual control (with the OOM trade-offs clearly spelled out).

First, the Symptom: Slower, With Unused VRAM

The telltale signature is a combination of three things that appear together, usually right after a git pull or an update to a recent build:

1. Throughput drops — the same workflow takes more seconds-per-iteration than before.
2. VRAM sits at roughly 45–55% of your card in NORMAL_VRAM mode, even though the model could use far more.
3. The model “thinks” for a while before sampling — a visible stall where ComfyUI seems to be computing or moving weights into memory before the first step actually runs.

This exact pattern was reported in ComfyUI issue #11081, titled “Performance Regression: GGUF models run noticeably slower with only ~50% VRAM usage after removing WAN Block Swap node.” The reporter and multiple commenters measured the same thing: a 16 GB RTX 4080 holding only 7–9 GB of a GGUF model in NORMAL_VRAM mode, with slower generation than the old manual-offloading behavior that filled 80–90% of the card.

The Root Cause: The Block Swap Node Became a No-Op

To understand what changed, you need to know what the wanBlockSwap node was and what happened to it. The node existed to let you run Wan video models on a GPU that technically cannot hold them by paging some of the model’s transformer blocks out to CPU RAM and swapping them back in during the forward pass. Up to 40 blocks could be shuffled off the card, trading speed for a lower VRAM floor.

What changed is that ComfyUI core eventually added automatic memory offloading. Core now decides how much to page to CPU based on your actual VRAM, without needing any node in the graph. Once that landed, the manual wanBlockSwap node was redundant — and, crucially, it could fight the built-in offloading, which is what produced instability. So ComfyUI core now intercepts the wanBlockSwap class and swaps in a no-op. As documented on the official node reference (comfy.icu / wanBlockSwap): “on a current ComfyUI, you’re installing a passthrough.”

The node is not broken — it is deliberately switched off. You can leave it in an old workflow and lose nothing, or delete it and lose nothing. That part is expected behavior.

The unexpected part is what came next. For many users, ComfyUI’s built-in auto-offloading turned out to be more conservative than the old manual block swap — it leaves more VRAM on the table, which in some cases means slower generation. The issue thread documents maintainers acknowledging the offloading “is due for a recalibration” and asking for benchmark data to repro the discrepancy.

Diagnose It on Your Own Machine Before Touching Anything

Before you start flipping flags, confirm the regression is actually what you’re hitting. The fastest way is to run a known workflow once and watch the numbers.

Step 1 — Watch VRAM during a real run:

watch -n 1 nvidia-smi

Run your workflow and note two numbers: the peak VRAM during sampling, and the peak during the text-encoder / model-load phase. If the sampling peak is stuck at ~50% of your card while you’re in NORMAL_VRAM mode (no --lowvram/--medvram flags), you’re seeing the conservative offload.

Step 2 — Confirm how you launched ComfyUI: check the exact command line, because the flags you did (or didn’t) pass are the entire story here.

ps aux | grep main.py

Step 3 — Check whether offload features are enabled: on a current Nvidia build, --async-offload is on by default, and dynamic VRAM is auto-enabled. These defaults are part of what changed. If you launched with no memory flags at all, you’re running the new default behavior — which is exactly the behavior people are reporting as slower.

Important caveat from the issue thread: --disable-async-offload and --disable-pinned-memory (the latter used in some tests) are performance-critical, so treat them as diagnostic toggles, not permanent fixes.

The Flags That Give You Control Back

All of these are documented in the official ComfyUI startup-flags reference. Here is what each one actually does and when it helps.

--reserve-vram (the “trick” that’s actually a real flag)

--reserve-vram <GB> tells ComfyUI how much VRAM to reserve for your OS and other software. The default is OS-dependent. People in issue #11081 discovered that passing a negative value — for example --reserve-vram -1 — effectively “tricks” the memory estimator into using more of the GPU, because the reserved amount is treated as less than the real requirement. This is the one the thread calls “just a funny trick,” and it comes with a serious caveat: squeezing the estimator too far produces OOM crashes.

How to try it:

python main.py --reserve-vram -1

Start small and validate with a real generation. If it OOMs, back off toward 0 or a small positive value. This is a heuristic, not a guaranteed win — but it is the single most direct way to push ComfyUI to use more of a card it is leaving idle.

--disable-async-offload

Async offload moves weights you’re about to use to the GPU ahead of time while earlier computation finishes. It’s on by default on Nvidia. The catch, noted explicitly by a maintainer in the thread, is that it is not implemented for ComfyUI-GGUF. So on GGUF models in particular, async offload can actually slow down the text-encoder phase rather than speed it up. Disabling it is a legitimate thing to test:

python main.py --disable-async-offload

Test both states on the same workflow and time it. On a GGUF model you may see a measurable difference; on non-GGUF models the results are less predictable.

--disable-dynamic-vram

Dynamic VRAM is auto-enabled on Nvidia (and ROCm 7.14+). It’s part of the newer automatic memory management that displaced the manual block-swap node. Disabling it reverts to estimate-based model loading:

python main.py --disable-dynamic-vram

Some users report this returns their old (fuller, faster) VRAM usage pattern. Like everything here, it’s empirical — flip it, measure, keep or revert.

One more flag worth knowing about while you’re in there: --disable-smart-memory makes ComfyUI aggressively offload to RAM instead of keeping models resident. It’s the opposite direction from what you want when the complaint is unused VRAM, but it’s useful to know the full dial exists so you don’t confuse it with the flags above.

Common Pitfalls When You Start Tuning

Pitfall 1 — Fighting the built-in offloader instead of tuning it. The whole reason the wanBlockSwap node was disabled is that manual offloading conflicts with core’s automatic offloading. Don’t go reinstall an old manual swap node and stack it on top — you’ll reintroduce the instability that got it removed. If you genuinely want manual block control, the documented route is Kijai’s ComfyUI-WanVideoWrapper, which still exposes a real, working block-swap control.

Pitfall 2 — Disabling the performance flags permanently. --disable-async-offload and --disable-pinned-memory are performance flags. Pinned memory in particular matters. Maintainers in the thread explicitly warned that these options are “performance critical.” Test them, but don’t bake them into your permanent launch script without measuring the net effect first.

Pitfall 3 — Judging the fix off the loading stall alone. The 3–5 minute “thinking before it loads” stall some users report is a separate symptom from steady-state throughput. Time the sampling iterations (seconds-per-iteration), not total wall-clock, when comparing flag configurations. That’s the number that tells you whether you actually got faster.

Pitfall 4 — Assuming every update caused it. If you roll back ComfyUI and the behavior persists, it’s not a simple regression on a single commit — the issue thread notes users who downgraded still saw the new behavior, because other components (like the Template package) also need to be downgraded in lockstep. Treat a full rollback as a multi-component operation, not a one-file swap.

Verification: How to Know You Actually Fixed It

After you’ve picked a flag combination, verify with numbers, not vibes:

1. Peak VRAM during sampling should now be meaningfully higher (closer to your card’s real capacity) than the ~50% you started from.
2. Seconds-per-iteration on an identical seed/prompt should be lower.
3. Run it three times and confirm no intermittent OOM — an estimator trick that works once and crashes on the fourth run is not a fix.
4. If you’re on a 16 GB card and the model legitimately doesn’t fit at full precision, confirm your GGUF quantization choice hasn’t quietly changed — the offloading regression and a changed quant can mask each other.

For a deeper look at how offload flags interact with your specific card, see our earlier piece on ComfyUI --lowvram vs --novram vs --normalvram, and for the block-swap basics themselves, our guide on how block_swap and offload_device actually work in ComfyUI.

Conclusion

The slowdown is real, it’s caused by a deliberate architectural change (the wanBlockSwap node becoming a no-op in favor of core auto-offloading), and the fix is a matter of re-taking manual control over a memory estimator that is currently more conservative than the old behavior. The levers are --reserve-vram (including the controversial negative-value “trick”), --disable-async-offload for GGUF models where async offload isn’t implemented, and --disable-dynamic-vram to revert to estimate-based loading. Every one of these is empirical — measure seconds-per-iteration and peak VRAM, watch for intermittent OOM, and don’t permanently disable performance flags you haven’t A/B tested. The maintainers have flagged the offloading as due for recalibration, so the clean fix may arrive upstream — but until it does, these flags are the difference between a card that’s half-used and one that’s earning its price.

Here’s a sequence every LLM-automation engineer eventually hits. You build a pipeline that calls a model, tells it to “respond in JSON,” and parses the result with json.loads(). It works in testing. A week later, in production, a downstream step silently fails because the model returned {"sentiment": "pos", "score": 0.9} instead of "positive". Your parser didn’t crash — there was no exception anywhere — the data was just wrong.

The trap is subtle: valid JSON is not the same as correct JSON. This article explains the difference between two features that are easy to conflate — JSON Mode and Structured Outputs — and gives you a concrete validation layer that catches the corrupt cases your json.loads() call can’t.

The Symptom: Silent Corruption, Not a Crash

The most dangerous failure mode in LLM automation is not an exception. It’s the response that parses cleanly but is semantically wrong. Consider a review-classification node that should return one of three enum values: positive, negative, or neutral.

If you only check that the string is parseable JSON, each of these passes:

• {"sentiment": "pos", "score": 0.9} — enum drift. “pos” is valid JSON but not a valid enum member.
• {"score": 0.5} — missing required key. The parser happily reads sentiment as None downstream.
• {"sentiment": "positive", "score": 0.9, "confidence": 0.99} — hallucinated field. Nothing rejects it, so it flows into your data store.

None of these raise a json.JSONDecodeError. I verified this directly: a plain json.loads() call accepts an invalid enum value without complaint, because json.loads() only checks syntactic validity, not semantic constraints. That single gap is responsible for a large share of “it worked yesterday” automation bugs.

Two Features, Two Different Guarantees

The confusion starts because providers ship two overlapping options under the same response_format parameter, and their names don’t make the guarantee obvious. Both are documented on the OpenAI platform (Structured Outputs guide), and the distinction carries over to most OpenAI-compatible APIs.

JSON Mode (type: "json_object")

JSON Mode promises exactly one thing: the response is valid JSON. The model will emit a syntactically correct JSON document — no trailing commas, no unquoted keys, no prose around the object. That’s it. The model takes no instruction from you about which keys to include, what types they should be, or what enum values are allowed. Ask it for {"a": 1} and it may decide to return {"b": "hello"}, and that’s still a correct answer under JSON Mode’s contract.

Historically, JSON Mode also had a documented quirk: many providers required the word “json” to appear in your message before json_object mode would engage, otherwise the request could be rejected or fall back to plain text. That “rejection trap” is a common source of surprise on older model versions.

Structured Outputs (type: "json_schema" with strict: true)

Structured Outputs goes further. You supply a full JSON Schema, and the provider guarantees the model’s output will conform to that schema. Per the official documentation, this means you no longer need to validate or retry around “omitting a required key, or hallucinating an invalid enum value.” The model is constrained at decode time, not just asked politely.

Key requirements and behaviors to know:

• Strict mode requires additionalProperties: false on every object in the schema, and every field must be in required. This forces a closed, fully-specified shape.
• Explicit refusals become programmatically detectable. If the model refuses for a safety reason, you get a structured refusal field instead of an empty or prose reply.
• Supported-schema limits apply. Not every JSON Schema feature is supported (some advanced constructs are rejected or ignored), so test your schema against the live endpoint before shipping.

Here’s the practical effect summarized: JSON Mode says “output will parse.” Structured Outputs says “output will match your contract.” For automation, the second one is usually what you actually wanted.

Diagnosis: Which Mode Does Your Client Actually Use?

Before you throw validation code at the problem, confirm what your client is really sending. A very common bug is assuming you’re in Strict Structured Outputs mode when your SDK is actually falling back to plain JSON Mode — or to free-form text — because the request didn’t match the strict schema requirements.

Check three things:

1. Confirm the exact response_format object in your outgoing payload. Enabling json_schema requires a nested structure: {"type": "json_schema", "json_schema": {"name": "...", "strict": true, "schema": {...}}}. Omitting strict or mis-nesting the keys silently downgrades the guarantee.
2. Validate your schema has additionalProperties: false and no unsupported constructs. A schema that fails strict-mode validation is often refused, and some clients mask that refusal by retrying in a looser mode.
3. Check whether the SDK exposes a typed parse path. The OpenAI Python and TypeScript SDKs let you pass a pydantic.BaseModel or a Zod z.object directly (via client.chat.completions.parse(...)), which wires the schema into Structured Outputs for you and returns a parsed object. If you’re hand-rolling the JSON and parsing manually, you may have accidentally skipped that path.

If you’re on a local model or a provider that doesn’t support json_schema at all, you don’t get the guarantee regardless of what you name the parameter — which is exactly when the defensive validation below stops being optional.

The Fix: A Validation Layer That Catches What json.loads() Misses

Whether or not your provider enforces the schema server-side, keep a parse-and-validate step in your pipeline. Server-side constraints reduce failures; client-side validation catches the rest and gives you a clean retry signal.

The minimum viable validator checks three things that pure json.loads() does not:

1. Required keys are present. Iterate your required list and assert each key exists.
2. Enum values are legal. For any field with an enum, test membership explicitly.
3. No unexpected keys (when closed). With additionalProperties: false, reject any field outside the allowed set.

Here’s a compact Python implementation using jsonschema, the reference validator for JSON Schema. It re-uses the exact same schema you’d send to a Structured Outputs endpoint, so there’s a single source of truth for the contract:

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "sentiment": {"type": "string",
                      "enum": ["positive", "negative", "neutral"]},
        "score": {"type": "number", "minimum": 0, "maximum": 1}
    },
    "required": ["sentiment", "score"],
    "additionalProperties": False
}

def parse_and_check(raw: str):
    obj = json.loads(raw)          # step 1: syntactic
    validate(instance=obj, schema=schema)  # step 2: semantic
    return obj
try:
    result = parse_and_check(response_text)
except json.JSONDecodeError:
    # real parse failure — safe to retry
    retry()
except ValidationError as e:
    # valid JSON, wrong shape — retry or surface the specific violation
    log_validation_error(e)

The key structural choice is separating the two failure types. A JSONDecodeError means the model didn’t even produce JSON — almost always worth a retry. A ValidationError means the JSON parsed but violated your contract — a stronger signal that you should either retry with a more explicit prompt or fix how the schema is being communicated. Logging these separately is what turns a mysterious downstream failure into a diagnosable one.

I ran the enum-drift case through this validator and confirmed the behavior: json.loads() accepts {"sentiment": "pos", "score": 0.9} with no error, while jsonschema.validate() rejects it on the enum constraint. That one-line difference is the gap between a corrupted pipeline and a caught error. (The example above is a self-contained pattern you can run locally; the exact jsonschema error text varies by version.)

Common Pitfalls That Reintroduce Drift

Even with both modes understood, several habits quietly undo your work:

• Relying on prompt wording instead of schema. “Return JSON with these fields” is a suggestion, not a constraint. A model under load will occasionally drop a key or restructure the object. Only a schema (server or client side) closes the gap.
• Parsing with a regex or .json() shortcut. Stripping surrounding prose with a regex and then calling json.loads() still skips semantic validation. You’ve fixed the framing, not the contract.
• Treating additionalProperties as optional. If your schema is open, the model can invent fields, and open schemas also break strict-mode eligibility on providers that require additionalProperties: false.
• Not handling the refusal field. When Structured Outputs models refuse, they can populate a refusal field instead of your keys. Your required validation will then trip — correctly — but you should branch on refusal before treating it as a plain schema failure.

Verification: How to Know You’re Actually Protected

Ship the fix only after proving the failure is caught. A three-part check gives you confidence:

1. Feed a known-bad enum value (“pos”) through your parse-and-check path and confirm it raises a ValidationError, not silently passing.
2. Feed a missing-key object and confirm the required check fires.
3. Feed a hallucinated extra field and confirm additionalProperties: false rejects it.

If all three fire, your pipeline now distinguishes “parseable but wrong” from “correct,” and your automations stop failing in ways that leave no trace in the logs.

Conclusion

The lesson generalizes well beyond any single model or provider: syntactic validity is the cheapest possible guarantee. If your automation depends on an LLM’s output shape — for a database write, a downstream API call, or a routing decision — the bare minimum is a validation layer that checks the semantic contract, not just whether json.loads() succeeded. Use Structured Outputs with strict: true where your provider supports it, and mirror the same schema in a client-side jsonschema validation step regardless. That pair turns “it worked yesterday” bugs into one caught, logged, and retryable error.

For more on keeping LLM-driven pipelines reliable, see our pieces on handling 429 rate-limit errors and building a reliable Python harness around a JSON API.

Alibaba’s Wan 2.7 release in April 2026 changed what “local video generation” means. Unlike Wan 2.2, which open-sourced only text-to-video, Wan 2.7 ships text-to-video, image-to-video, image generation, image editing, and video editing under a single Apache 2.0 license. That license is the reason the model spread fast: personal use, commercial use, LoRA training, and even redistribution of your fine-tunes are all permitted without owing Alibaba anything.

The catch is the hardware bar. Wan 2.7 is a roughly 14-billion-parameter model, and video diffusion is the most VRAM-hungry workload in the open-source stack. This guide is a planning resource for anyone deciding whether their current GPU can run it, and exactly what the GGUF-quantized fallback buys you on a sub-24GB card. It is a documentation analysis, not a benchmark claim — I have not run Wan 2.7 locally on this machine, and I will say clearly where the numbers come from.

Why Wan 2.7 Resets the VRAM Conversation

Wan 2.2 needed a single diffusion model plus a text encoder to generate one short clip. Wan 2.7 keeps that core architecture but expands the surface area: first-frame and last-frame control, reference-image-to-video, and native 1080p output are all new, and each new mode loads additional conditioning into memory during generation.

The practical consequence is a clean, if blunt, split. A card with 24GB of VRAM — the ComfyUI ecosystem’s default reference point for video models — can load the full-precision 14B weights and generate 720p clips. Below 24GB you enter quantization territory, where you trade output quality for the ability to load the model at all. This is the same tradeoff I walked through for Wan 2.2 Animate on a 16GB card in my BlockSwap breakdown: there is a real difference between a model that fits and a model that runs well.

The VRAM Tiers, In Plain Terms

Community deployment guides and the model card converge on a consistent tiering. Treat these as planning bands, not exact measurements, since batch size, resolution, and frame count all shift the real number.

• 24GB (RTX 4090, RTX 3090): Full-precision video works. Expect a 5-second 720p clip to land in the single-digit-minutes range on a 4090, slower on a 3090. This is the comfortable tier.
• 16GB (RTX 4080, RTX 5060 Ti): Must use GGUF quantization plus aggressive offload. Image generation works cleanly; video is slow and quality drops.
• 12GB (RTX 4070): GGUF-only, and video becomes a patience exercise. Image-to-image and still-image generation are the realistic use cases.
• 8GB (RTX 4060): Video is effectively out of reach. Still-image generation is borderline and usually not worth the setup friction.

The one number to internalize: 24GB is the practical bar for Wan 2.7 video work, and everything below it is a managed compromise that you should enter knowingly, not accidentally.

Diagnosing Whether Your Card Can Do the Job

Before you download a 30–40GB model variant, spend five minutes confirming the environment is sound. Two commands catch most of the failures that look like “the model is broken” but are actually environment problems.

First, confirm what VRAM you actually have and what is already resident on the card:

nvidia-smi

Second, confirm PyTorch can see CUDA at all — a surprising number of local setups fail here because the CUDA toolkit and the installed PyTorch wheel were built for different versions:

python -c "import torch; print(torch.cuda.is_available())"

If either command errors, fix the environment before downloading weights. This mirrors the failure pattern I documented for GGUF “failed to find quantized version” errors, where the loader, the dependency, and the CUDA backend form a single failure chain that has to be verified in order.

The GGUF Quantization Path for Low-VRAM Cards

GGUF is the community’s answer to the 24GB wall. The same quantization format that made large language models run on modest GPUs is applied to the Wan 2.7 diffusion weights, producing smaller variants that fit on 12GB and even 8GB cards. You trade it directly against the model’s own precision-weighted pathways, which is why quantized video output is visibly softer and more prone to artifacts than the full model.

The workflow in ComfyUI is consistent with other GGUF video paths: install the Wan video custom node through ComfyUI Manager, point it at the quantized weights, and load a community example workflow rather than building the graph from scratch. The first run is always the slowest because the model has to compile; after that it stays resident and repeat generations are faster.

Two honest caveats worth stating up front. First, quantization is not magic — a 14B model doesn’t become a 7B model; it becomes a 14B model expressed with lower numerical precision, and the quality gap widens as you drop to lower bit-widths. Second, offloading layers to system RAM (the same blocks_to_swap / offload_device mechanism I covered for Wan 2.2) can paper over the gap, but it transforms a VRAM problem into a memory-bandwidth problem and usually slows generation to the point that short clips become the only practical output.

Model Sources and License Verification

Weights are distributed in three places, and the right choice depends on your network, not your hardware. ModelScope is Alibaba’s own platform and is the fastest option for mainland China and much of Asia. HuggingFace hosts the full set under the Wan-AI organization and is the default for most of the rest of the world. GitHub hosts the inference code and documentation under the Wan-Video organization, but no weights — a distinction worth keeping straight because many walkthroughs blur it.

On the license itself: verify the Apache 2.0 header on the model card before building anything commercial. It is the most permissive mainstream license available, but “open weights” and “open source” are still formally different, and the training code and dataset for Wan 2.7 have not been released. You can use, fine-tune, and ship the model for free; you cannot reproduce the training pipeline. For almost everyone building on it, that distinction is academic — but for a commercial project, it is the difference between a claim you can defend and one you can’t.

What to Actually Do, Step by Step

If you have decided your card sits somewhere on the Wan 2.7 spectrum, here is the sequence that minimizes wasted downloads and false starts:

1. Run nvidia-smi and the PyTorch CUDA check above. Do not proceed until both are clean.
2. Decide your tier: 24GB goes full-precision; 12–16GB goes GGUF; 8GB should stop at still images or reconsider the project.
3. Check available disk. A single variant is 30–40GB, and downloading all modes can exceed 100GB.
4. Install ComfyUI Manager, then search for the Wan 2.7 node set and install it.
5. Download the correct variant from ModelScope or HuggingFace into the node’s expected model directory — directory-contract mistakes are the most common zero-output failure.
6. Load the node author’s example workflow, not a hand-built graph, for the first successful generation.
7. Generate one short, low-resolution clip and verify it end-to-end before scaling up resolution or frame count.

The discipline of a single end-to-end verification run before scaling is the difference between a working pipeline and a folder full of half-downloaded weights. It is the same validation-first habit I recommend for any 16GB production pipeline.

Conclusion

Wan 2.7 is a genuinely meaningful step for local generation because the Apache 2.0 license removes the commercial friction that held back earlier releases. But the license is the easy part. The hard truth is that a 14-billion-parameter video model still wants 24GB of VRAM for a comfortable experience, and every card below that threshold is a negotiation. If you have a 24GB card, Wan 2.7 is a straightforward upgrade. If you don’t, the GGUF path is real but conditional — workable for stills and short clips, honestly disappointing for serious video. Decide your tier first, verify your environment second, and only then spend the time and bandwidth on 40GB of weights.

I ran llama-server --version on a Linux box this morning and got exactly two lines back: a bright red error while loading shared libraries: libllama-common.so.0: cannot open shared object file: No such file or directory, followed by nothing. The llama-cli binary right next to it failed the same way, only it complained about a different file, libllama-cli-impl.so.

This is not a model problem. It is not a CUDA problem. It has nothing to do with your GGUF file or your GPU. It is a library installation problem, and it is one of the most common ways a working llama.cpp setup breaks after an upgrade, a partial make install, or a cleanup that removes files it should not have touched. It is the same category of silent environment breakage I have seen flip ComfyUI workflows from working to dead overnight, which I covered in this guide to llama.cpp CUDA out-of-memory on a 16GB card.

In this article I walk through the exact failure on a real machine, the three commands that pinpoint the root cause, the difference between a missing library and a misconfigured search path, and the fix that actually works. Everything below is reproduced from a live Raspberry-Pi-free Ubuntu host running an NVIDIA RTX 5060 Ti.

The symptom: an error that names a file you have never heard of

The first thing to notice is that both binaries fail, but with different filenames. On the machine I was debugging, the two failures looked like this:

$ /usr/local/bin/llama-server --version
error while loading shared libraries: libllama-common.so.0: cannot open shared object file: No such file or directory

$ /usr/local/bin/llama-cli --version
error while loading shared libraries: libllama-cli-impl.so: cannot open shared object file: No such file or directory

Two different missing files, two different binaries. That is the key clue that this is a partial install rather than a global LD_LIBRARY_PATH problem. If the loader simply could not find a directory, both binaries would fail on the same library. When each binary names its own private library, the libraries themselves are gone from disk.

This splitting behavior is relatively new. Modern llama.cpp is built as a set of shared libraries — libllama-server-impl.so, libllama-cli-impl.so, and a shared libllama-common — that the thin executables link against. Older builds produced a mostly self-contained llama-cli and llama-server. If you installed a recent version and any of these impl libraries did not make it into your library path, you get exactly this class of error.

Step 1: confirm it is really the library and not the environment)

Do not start editing LD_LIBRARY_PATH yet. First, determine whether the loader cannot find the library or the file genuinely does not exist. These two tools answer that in seconds.

ldd — what is the binary actually asking for?

$ ldd /usr/local/bin/llama-cli
        libllama-cli-impl.so => not found
        libstdc++.so.6 => /lib/x86_64-linux-gnu/libstdc++.so.6
        libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6

The => not found next to libllama-cli-impl.so is the smoking gun. Every other dependency resolved to a concrete path; only this one failed. That points at the specific missing file.

readelf — the declared dependency, not the guess

ldd runs the loader and can be influenced by your current LD_LIBRARY_PATH. To read the dependency that was baked in at link time, check the ELF metadata directly:

$ readelf -d /usr/local/bin/llama-server | grep NEEDED
 0x0000000000000001 (NEEDED)  Shared library: [libllama-server-impl.so]
 0x0000000000000001 (NEEDED)  Shared library: [libstdc++.so.6]
 0x0000000000000001 (NEEDED)  Shared library: [libgcc_s.so.1]
 0x0000000000000001 (NEEDED)  Shared library: [libc.so.6]

Here is the subtle part that trips people up. llama-server declares a dependency on libllama-server-impl.so, and that file does exist on disk. But loading that impl library then fails on its own transitive dependency, libllama-common.so.0. The top-level readelf output looks clean; the missing library is one level deeper. That is why the error for the server names libllama-common.so.0 while the CLI names libllama-cli-impl.so — they are failing at different points in the dependency chain.

Step 2: search the whole filesystem for the missing library

Once you know the exact filename, search everywhere, not just /usr/local/lib:

$ find / -name "libllama-common*" 2>/dev/null
# (no output — the file does not exist anywhere on disk)

$ find / -name "libllama-cli-impl*" 2>/dev/null
# (no output — also absent)

An empty result is the decisive answer. If find turns up nothing, no amount of LD_LIBRARY_PATH or ldconfig configuration will save you — the bytes simply are not on the machine. The install is incomplete or was partially removed.

Contrast this with the libraries that are present. On the same host, /usr/local/lib contained libggml.so, libggml-base.so, libggml-cpu.so, libggml-cuda.so, libllama.so, and libllama-server-impl.so — but not libllama-common.so.0 and not libllama-cli-impl.so. That pattern is the signature of a build where the shared-library split was introduced, and the libllama-common target either failed to build or failed to install.

Step 3: check the library path is even registered

Even after you restore the missing files, the loader still needs to know where to look. A very common second failure — separate from the missing-file problem — is that /usr/local/lib is not in the linker’s search path. Verify it:

$ cat /etc/ld.so.conf.d/*.conf | grep local
/usr/local/lib
/usr/local/lib/x86_64-linux-gnu

If /usr/local/lib is not listed, that is a different fix: create a drop-in config and rerun the cache. It is worth ruling out even when you have already confirmed files are missing — the two problems frequently occur together after a botched upgrade.

There is a third, quieter failure mode worth knowing about too. On this host, running sudo ldconfig emitted a stream of warnings like ldconfig: /usr/local/lib/libggml-base.so.0 is not a symbolic link. That happens when real files were copied over the place where versioned symlinks should live. It does not stop the loader, but it is a strong signal that a manual file copy — rather than a clean cmake --install — created the /usr/local/lib contents.

The fix: repair the partial install, then rebuild the linker cache

Because the root cause here is missing files, not misconfiguration, the correct fix is to rebuild llama.cpp from a clean tree and reinstall it fully. A quick workaround — copying a libllama-common.so.0 from another machine or a downloaded release bundle into /usr/local/lib — can restore the binaries, but it leaves out the build’s own notion of which symbols belong to which library and tends to break again on the next upgrade.

1. Clone or update a fresh checkout and build the shared-library targets:

$ git clone https://github.com/ggml-org/llama.cpp
$ cd llama.cpp
$ cmake -B build -DGGML_CUDA=ON
$ cmake --build build --config Release -j
$ sudo cmake --install build

The cmake --install step is the important one — it places all produced libraries (libllama-common, libllama-server-impl, libllama-cli-impl, the libggml-* family) into the right location together, which is exactly what a manual copy misses.

2. Refresh the dynamic-linker cache so the new libraries are registered:

$ sudo ldconfig

3. Verify both binaries now load, and check that no NEEDED entry remains unresolved:

$ /usr/local/bin/llama-server --version
$ ldd /usr/local/bin/llama-cli | grep -i "not found"
# (empty output means everything resolved)

The cleanup advice is to prefer release packages over sudo make install for production boxes. A release tarball or a distro package bundles every library the binaries need; a manual make install relies on the target list being complete, and it is precisely where the libllama-common split has bitten people.

Common traps that are not the problem

There are a handful of things people assume caused this error that almost never do, and chasing them wastes an afternoon.

• Your GGUF model is corrupt. No — the binary fails before it ever opens the model file. Loader errors happen at process start, before llama-server parses any weights.
• Missing CUDA driver. A bad CUDA setup produces a different message (CUDA error: no kernel image is available or a libcuda.so failure), not a missing libllama-common.
• Wrong --n-gpu-layers. That only affects runtime VRAM allocation, never dynamic loading.
• You need to re-download the model. The model is fine. Deleting a 16 GB GGUF to “fix” a loader error only wastes bandwidth.

The one genuinely confusing case is a wrong library version: when libllama-common.so.0 exists but is from an incompatible llama.cpp build, the error changes to something like undefined symbol or a GLIBC version mismatch rather than “not found”. If you see undefined symbol, treat it as a version-mismatch, not a missing file, and rebuild the entire library set together instead of copying one file.

Verification checklist

After the fix, work through these four checks in order and only move on when each is clean:

1. llama-server --version prints a version instead of a loader error.
2. llama-cli --version prints a version.
3. ldd /usr/local/bin/llama-cli shows no => not found lines.
4. A minimal generation (llama-cli -m model.gguf -p "hi" -n 1) produces tokens rather than a shared-library error.

Conclusion

An error while loading shared libraries from llama.cpp is a library-installation failure, not a model or GPU failure, and it is usually one of exactly two things: a library file that is missing from disk, or a library path the loader has not been told about. The three commands that separate the two are ldd (what is unresolved), readelf -d (what the binary declares it needs), and find (does the file exist anywhere). If find comes up empty, rebuild and reinstall — do not paste LD_LIBRARY_PATH exports over a genuinely absent file and expect it to work.

If you run llama.cpp on a single-GPU Linux box, this class of error will eventually find you after an upgrade. Knowing it is a loader problem from the first line of the message — and not a rabbit hole into CUDA, models, or VRAM flags — is the part that saves the most time.

The claim worth testing

A 27B model on an 8GB graphics card. Every guide I found said you need 24GB for this class of model, and the quantization charts back that up at first glance. But look closer at the IQ4_XS row and the picture changes: roughly 6% quality loss against the base model, with the file size dropping to about 14GB.

14GB does not fit in 8GB. So the honest question That is what this post is about, because the benchmarks do not answer it.

What the settings actually were

If you want to reproduce this, the configuration matters more than the model choice.

**Quantization:** Unsloth IQ4_XS. Standard practice for a small card.

**KV cache:** Quantized to 4-bit. This is not optional at this size. Without it your context window eats the VRAM you needed for the model itself. There is a trap here worth knowing about: quantizing the KV cache can silently push work onto the CPU, and I walked through why that made prefill 30x slower in llama.cpp rather than assuming it helped.

**Context:** 70K tokens. Deliberately modest. If you are running at 8GB you should be picking the smallest context that gets the job done, not the largest one that fits.

**Offload:** Around 26 layers sent to the GPU. The rest lives in system RAM. Total VRAM landed around 7GB, which leaves room for the operating system, and you will need that room. If you want to understand what the offload flags are actually doing, ComfyUI’s –lowvram vs –novram vs –normalvram comparison covers the same mechanics in a different runtime.

**CPU threads:** Set to match the physical core count. Six cores, six threads. Setting this to your logical core count is a common mistake and it makes things worse, not better.

**Speculative decoding:** MTP mode with 2 max draft tokens. If this is unfamiliar, the HuggingFace writeup on assisted generation explains the mechanism.

**Sampling:** Temperature 1, top-k 20, repeat penalty 1, min-p 0. These come from the quantization author’s recommendation, which is usually a better starting point than whatever the model card says.

The two things that will waste your afternoon

This is the part the videos skip, and both cost real time.

**First: disable the HTTP timeout in your harness.** The generation speed on this setup is genuinely slow, slow enough that the timeout fires and kills the tool call before the model finishes writing. If you see the model apparently stuck in a loop when it is trying to write output, this is what is happening. It is not looping. It is being cut off.

**Second: raise your max output tokens.** For the same reason, writing a large file will trip the default limit and the process gets terminated mid-write. The default exists to protect you from runaway generation on fast hardware. On an 8GB card it just breaks your work.

One more setting matters here, and it is not a bug.

**Remove the reasoning budget, and keep thinking enabled.** This sounds contradictory and it is not. The model uses an enormous number of tokens thinking. One moderately sized prompt consumed about 20,000 tokens just on reasoning before producing any output. If you cap that, the model gets cut off mid-thought and the output quality collapses. On slow hardware the thinking is expensive, but it is the thinking that makes the model good. Cutting it to save time defeats the point of running the model at all.

What the numbers looked like

Four tasks, all completed in a single shot with no agent looping.

A Minecraft 3D landing page took two and a half hours. Average throughput was 4.2 tokens per second, starting near 6 and degrading as context grew. The same prompt through a frontier model produced a comparable result.

A cyberpunk neon city 3D scene took about an hour and a half at roughly 5 tokens per second.

A detailed personal website prompt took two hours at 4.6 tokens per second.

An interior design company landing page took an hour and a half at 5 tokens per second.

The degradation is the interesting part. You do not get a steady 5 tokens per second. You get 6 at the start and 4 by the end, and the decline tracks context length. That is the cost of KV cache growth on a card that has no room for it, and it is why long chats slow to a crawl on setups that looked healthy at the start.

Is this actually useful

Honest answer: it depends what you want.

If you need an interactive assistant, 4 tokens per second will drive you up the wall. You will wait on every response.

If you need something to grind on a well-specified task while you do something else, it works fine. Two and a half hours for a landing page is not a workflow. It is a background job. Treat it that way and the numbers stop being disappointing.

Five hours of the afternoon went into the two problems described above. Almost none of it was model tuning. The two failures that cost the most time were a timeout setting and a token limit. Neither is a machine learning problem. Both are the kind of thing you only find out about by actually running the thing, which is exactly why a working configuration and an honest account of what broke is more valuable than another benchmark table.

The transferable part

If you take one thing from this, take the shape of the problem rather than the specific numbers.

Small cards fail in a predictable order. First you run out of VRAM for the model, so you quantize. When the KV cache then becomes the problem, the fix is often counterintuitive. Then your context eats the space you saved, so you quantize the cache. Then you offload, and pay a bandwidth tax on every single token. Then the slowdown trips timeout and size limits you did not know were configured. Every one of those steps is where the real time goes, and none of them show up in a comparison chart.

The settings in this post were tuned for an 8GB card. On a 16GB card the same reasoning applies with different constants. The failure order is the same. The limits are just further out.

A note on where these numbers came from

I did not run this test. The configuration and timings come from a video walkthrough that tested Qwen 3.8 27B on a single RTX 4060, and I am relaying it here because the settings and the failure modes line up exactly with what I hit running a 14B video model on a 16GB card.

That is the reason this belongs on the site. The specific card differs, the model class differs, and the workload differs. The sequence of failures does not. You run out of memory, you quantize, the cache becomes the constraint, you offload, and then the slowdown breaks tooling that was never designed for how slow things got.

The two fixes that mattered most, disabling an HTTP timeout and raising an output token limit, are both the kind of thing you find by watching the process die rather than by reading documentation. That pattern has held for every local AI setup I have touched, and it is why I keep writing about the failures instead of the benchmark scores.

You downloaded a 14B fp8 checkpoint, wired up the workflow, hit Queue, and watched the terminal print the three words every local-AI tinkerer dreads: CUDA out of memory. The model file is 16 GB. Your GPU reports 15 GB. On paper the numbers are close—close enough that forcing it feels like it should work. In practice, whether it works comes down to two settings most people never read the source to understand: block_swap and offload_device.

This guide is written from a real migration: moving a 16.1 GB Wan2.2-Animate-14B-fp8 checkpoint onto a 15 GB RTX 5060 Ti. The model exceeds the card, so the only way it runs at all is by swapping and offloading transformer blocks on demand. The notes below are grounded in the actual node source (Kijai’s ComfyUI-WanVideoWrapper) and the official Wan2.2 repository, not from re-reading a tutorial. Let’s unpack each mechanism, in the order the model loader actually applies them.

Why a 16 GB model on a 15 GB card is a real problem

First, the arithmetic that trips everyone up. A .safetensors file of ~16 GB represents the serialized weights. When ComfyUI loads them in fp8, the resident size is roughly that number, but inference also needs activations, the text encoder, the VAE, and clip vision. None of that is free. The official Wan2.2 repository is explicit about the ceiling: its single-GPU generate.py for the A14B models states the command “can run on a GPU with at least 80GB VRAM,” while the compact TI2V-5B variant is the one documented to run on a 24 GB RTX 4090.

So a 14B model that tips over 15 GB sits in an awkward middle ground: too big to fit naively, small enough that a few GB of clever swapping should bridge the gap. That bridge is exactly what block_swap and offload_device provide—but only if you set them deliberately, because the defaults are conservative on purpose.

What block_swap actually does (and what it does not)

In the WanVideoWrapper node source, the model loader accepts a block_swap_args input and injects it into the transformer’s options as transformer_options["block_swap_args"]. This is a ComfyUI native feature, not a wrapper hack: it tells the diffusion transformer to keep only a slice of its blocks resident in GPU memory and page the rest from system RAM (or disk) as the sampler walks through them.

The number you set is a count of transformer blocks held in VRAM, not a byte value. Lower = less VRAM = more swapping = slower. On a 14B MoE model a common starting point is 20, which is also what many community Wan workflows default to. There is no “correct” value that works everywhere: the right number is a function of how many blocks the model has and how much VRAM you can spare after the encoder and VAE take their cut.

Two misconceptions to clear up immediately:

• Block swap is not quantization. Swapping moves weights between fast and slow memory; it changes speed, not precision. Your fp8 weights stay fp8.
• Block swap does not shrink the model. If you set it too high, you still OOM; too low, and generation crawls because every other block is a round-trip to CPU RAM.

offload_device and load_device: where things live between passes

The second half of the pair is the device routing. The wrapper pulls unet_offload_device() from ComfyUI’s model manager and, on the decoder side, moves the VAE, clip vision, and the video model onto offload_device before each encode. The force_offload flag you see sprinkled through the node defaults to True, which is what makes sequential workflows behave: after a component finishes its job, it is explicitly moved off the GPU instead of lingering in VRAM.

The practical consequence matters more than people realize. In a three-stage pipeline—text encode, then VAE/latent work, then the diffusion transformer—every one of those stages competes for the same 15 GB. Without force_offload, the text encoder you finished with eight seconds ago is still squatting on VRAM when the transformer tries to allocate, and you OOM on a stage that would have fit fine in isolation.

Here is the interaction to internalize: block_swap controls VRAM within the transformer’s forward pass; offload_device controls VRAM between stages. You need both. Setting block_swap to 4 but leaving the clip vision and VAE resident defeats the point, just as aggressively offloading everything but never capping the block count leaves the transformer itself overflowing.

A reproducible sequence for the 16 GB case

Rather than give you a magic number, here is the diagnostic sequence that surfaces the actual ceiling on your card. Run it once, in order, and watch nvidia-smi at each step (not just the final frame):

1. Baseline the card. With nothing queued, note free VRAM. If another process (a local LLM server, a second ComfyUI) is already holding gigabytes, that is your real budget, not the 15 GB on the box.
2. Load the model with block_swap at a high default (e.g. 20+). If it OOMs at load time rather than at sampling, your problem is not swap count—it is that the weights plus the encoders don’t fit at all, and you need a smaller quantization or a lighter encoder.
3. If it loads but dies on the first denoise step, lower block_swap incrementally (20 → 12 → 8) until the transformer’s resident footprint fits. Each drop costs speed, so stop at the highest value that stays under the ceiling.
4. Confirm force_offload is on for the text encoder, clip vision, and VAE so intermediate tensors don’t stack on top of the transformer.
5. Re-check between stages, not after. OOM late in the run is usually a stage-boundary leak, not the model being too big.

On this concrete case, the honest outcome of step 2–3 is worth stating plainly: a 16.1 GB fp8 checkpoint on a 15 GB card is genuinely at the edge, and the reliable fallback is the smaller 14B fp8 variant already on disk or the official 5B model, which the README explicitly targets at consumer cards. For more context on how these video models stack up against their closed-source rivals, see our earlier breakdown of Wan2.2 Animate versus the commercial options, and for the full consumer-hardware stack, running Wan2.2, CogVideoX and Mochi locally.

Common traps that masquerade as “not enough VRAM”

Most “OOM” reports are actually one of these four, and none are fixed by buying a bigger GPU:

• Leftover resident tensors. A prior run’s encoder or VAE still held in VRAM because force_offload was off. Residual memory makes the next run fail, which is why failures look intermittent.
• Wrong quantization for the card. fp8 e4m3fn is the sweet spot here; bf16 double weights won’t fit at all, and a mistagged dtype means you’re loading more precision than you think.
• The text encoder is the hidden hog. A full-precision umt5-xxl encoder alone can eat several GB. Offload it (or use its fp8 variant) before blaming the transformer.
• Resolution, not the model. At 480×832 for 49 frames the activation overhead is manageable; jump to 720p and the same model and block_swap value blow past the ceiling. OOM is often a resolution decision, not a model-weight problem.

How to verify a fix instead of guessing

The verification step is where most local-AI troubleshooting falls apart, because “it didn’t crash this time” is not evidence—it might just be a favorable seed or an empty queue. Verify with a deliberate loop:

1. Run the same workflow, same seed, three times in a row. One clean pass is luck; three is a configuration.
2. Watch peak VRAM across all three, not the average. A fix that leaves 200 MB of headroom only survives because of scheduling; give yourself at least a gigabyte of margin.
3. Compare generation time at the chosen block_swap value against the next-higher one. If dropping from 12 to 8 saves VRAM but doubles time, you found your speed/headroom trade-off point.

That three-run, nvidia-smi-watched loop is the difference between “it worked once” and a workflow you can actually queue overnight without babysitting.

Conclusion

A 14B fp8 model that’s a hair bigger than your VRAM is not a lost cause—it’s a budgeting exercise. block_swap caps how much of the transformer lives on the GPU at once, and offload_device / force_offload decides what else gets to sit there between stages. Set the first to the highest count that doesn’t blow the ceiling, keep the second on for every non-transformer component, and confirm with a repeated same-seed run watching peak (not average) VRAM. When the file genuinely won’t fit even at minimum swap, fall back to a lighter quantization or the 5B consumer-targeted model—that’s not surrender, it’s selecting the right tool for a 15 GB card.