Find where the image turns wrong
A black result is a symptom, not one fix. Keep the last frame that still looked right, then test model selection, sampling, Full VAE decode, postprocessing, and the saved file as separate stages.
Rebuild one valid image before changing precision
Most false diagnoses begin by changing five controls after seeing one black square.
Restart once. Select the matching sd, xl, or flux preset and one complete documented model package. Use batch 1, a fixed seed, Automatic low bits, Queue, CPU, Full VAE decode, and no Hires. fix, LoRA, ControlNet, LayerDiffuse, postprocessor, third-party extension, or custom performance flag. Run it twice.
If generation stops with a CUDA or host allocation failure, use the out-of-memory diagnostic. If the base output is valid and only a ControlNet unit breaks it, rebuild the pair with the full ControlNet workflow. This page owns completed but unusable image output.
Which frame was the first bad one?
Choose the closest reproducible shape. Each route changes one boundary and preserves the comparison.
- What it means
- The final VAE has not yet proved anything. A live preview can use Approx NN, Approx cheap, or TAESD rather than the final Full decoder.
- Do now
- Run the clean baseline with the correct UI preset, fixed seed, batch 1, Automatic low bits, no Hires. fix, no add-ons, and no custom performance flags.
- Keep the comparison
- Keep the saved final file. If the final file is normal, troubleshoot preview settings separately; a poor preview is not a failed generation.
- What it means
- Sampling produced a plausible latent preview, but Full decode, a postprocessor, an extension, or final conversion changed the result.
- Do now
- Disable Hires. fix, face restoration, ADetailer, LayerDiffuse, ControlNet, LoRAs, and third-party scripts. Verify the exact VAE or FLUX autoencoder required by the model package.
- Keep the comparison
- Retest Full decode first. TAESD is a different decoder and can isolate the boundary, but a TAESD image does not guarantee that the intended Full VAE is correct.
- What it means
- The first pass already succeeded. Hires. fix adds image resize, VAE work, another sampling path, and a later final decode.
- Do now
- Save the passing base checklist. Re-enable Hires. fix with batch 1, a smaller target, one upscaler, and no add-ons.
- Keep the comparison
- Record whether the last good image was before resize, before second sampling, or before final decode. Route an allocation error to the OOM guide.
- What it means
- A passing base image plus one failing add-on is a useful boundary. It does not guarantee Forge core, the base checkpoint, or every file of that type is broken.
- Do now
- Add one exact file to the passing baseline. For ControlNet, keep one unit, one preprocessor, one control model, one input image, and the correct model family.
- Keep the comparison
- If disabling all third-party extensions fixes it, enable one extension at a time. Preserve its repository and commit before reporting the conflict.
- What it means
- The same seed becoming black only after a named sequence points to process state, model switching, or an add-on that retained state—not to the prompt alone.
- Do now
- Restart once, run clean model A twice, switch to B, then return to A. Keep every other setting identical and use batch 1 without Hires. fix or LoRAs.
- Keep the comparison
- A restart is a clean comparison, not a root cause. Reproduce the shortest A → B → A sequence on a separate clean install before filing a regression.
- What it means
- A transparent PNG can appear black on a black viewer background. A preview composite can also contain a checkerboard while the separate output carries real alpha.
- Do now
- Open the exact saved PNG in a second alpha-aware viewer and place it over a bright color. Compare dimensions, color channels, alpha, and PNG Info.
- Keep the comparison
- If the saved file is correct, do not change sampling precision. If both copies are black, return to the first earlier stage that was still valid.
- What it means
- A completed but malformed output often needs a different test from numeric black output: preset/model-family mismatch, wrong companion modules, resize mode, or an add-on can change structure.
- Do now
- Use the correct preset and documented file set, restore family-appropriate base dimensions, remove control images and Hires. fix, then generate one fixed-seed base image.
- Keep the comparison
- If the base is normal, restore the resize or conditioning stage alone. Do not try precision flags before proving a numeric failure.
Prove the smallest complete package
The baseline removes later stages without inventing a universal sampler, step count, or resolution.
- 01
Keep the failed checklist
Save the final file, PNG Info or generation parameters, the complete console lines from model selection through save, and a screenshot of the selected files.
- 02
Start a clean process once
Close Forge normally, reopen the same installation, and do not load parameters from an old PNG until the model and UI preset are visibly correct.
- 03
Use one family-correct package
Choose sd, xl, or flux to match the checkpoint. For a split package, select only the exact VAE/text encoders documented for that package.
- 04
Remove later stages
Batch size 1, one image, fixed seed, no Hires. fix, ControlNet, LoRA, refiner, face restoration, ADetailer, LayerDiffuse, or third-party script.
- 05
Return precision and memory controls
Diffusion in Low Bits: Automatic. Swap Method: Queue. Swap Location: CPU. Remove custom precision, attention, stream, and pinned-memory launch arguments.
- 06
Generate the same baseline twice
Use the preset’s base dimensions or the model publisher’s documented dimensions. Two passing identical-stage runs establish the state to rebuild from.
A preview, decoded image, and saved file are different details
Record the last stage that was demonstrably correct and the first stage that was not.
| Stage | What Forge is using | Failure boundary | Details to keep |
|---|---|---|---|
| Model selection | UI preset, checkpoint, VAE / Text Encoder, low-bits choice | Wrong family, incomplete split package, stale selection | Screenshot plus console “Model selected” object |
| Conditioning | CLIP/T5, prompt, LoRA, ControlNet preparation | Incomplete encoder set, incompatible add-on, numeric instability | Last named component and clean prompt result |
| Sampling | UNet / diffusion model, sampler, scheduler, latent | Black/noisy latent, add-on patch, precision or state | Fixed seed, first bad step, sampler and scheduler |
| Live preview | Approx NN, Approx cheap, or TAESD preview | Preview-only quality or display difference | Preview method and saved final comparison |
| Full decode | Selected VAE / autoencoder turns latent into RGB | Wrong component, non-finite decode, decode-specific failure | Exact VAE filename, dtype line, Full versus isolated TAESD result |
| Postprocess | Hires. fix, restore, scripts, LayerDiffuse, extensions | Second-pass or extension-only output change | Last clean stage and one enabled feature |
| Save / view | uint8 conversion, PNG/JPEG, alpha, browser gallery | Cast warning, alpha interpretation, viewer difference | Saved file, format, alpha-aware viewer result |
NaN is a symptom, not a diagnosis
The current code path matters. Advice copied from older WebUI errors can target a check that Forge no longer performs.
Choose a flag only after the stage chooses it
A flag that makes a black square disappear can still leave the model package, decoder, or retained-state problem unexplained.
--disable-nan-check
current behavior: Current cmd parsing still accepts it, but test_for_nans already returns immediately on the current commit.
Use boundary: It cannot turn non-finite numbers into a valid image. Do not use it as a repair.
--no-half / --precision full
current behavior: Broad legacy controls that change more than the final decoder.
Use boundary: Not a first test. Use only when an exact environment-specific error and code path justify a global precision comparison.
--no-half-vae / --vae-in-fp32
current behavior: VAE-scoped precision controls; current backend precision choices are mutually exclusive.
Use boundary: Consider one isolated comparison only when sampling passes and Full decode is the proven boundary. Record startup VAE dtype before and after.
TAESD decode
current behavior: A separate approximate decoder available in Settings → VAE.
Use boundary: Useful to ask “can this latent be decoded another way?” It can look lower quality and does not validate the intended Full VAE.
--cuda-stream
current behavior: The earlier maintainer post explicitly warns about possible black/NaN output and stability limits.
Use boundary: Remove it during diagnosis. Queue is the controlled baseline.
xformers 0.0.18
current behavior: Current memory-manager code contains an explicit high-resolution black-image warning and disables xformers for VAE for that version.
Use boundary: Preserve the printed xformers version. Do not force-enable a version the current code warns about.
A visible file is not automatically a compatible component
Forge’s VAE / Text Encoder control discovers several file types in two folders. Compatibility still belongs to the model package.
Single-file SD / SDXL checkpoint
Start with no manually added VAE/text encoder unless the model publisher explicitly requires one. A baked component plus an unrelated override changes the package.
Split FLUX package
The diffusion model, CLIP-L, one intended T5 variant, and the correct autoencoder must form one documented set. The maintainer identified the official ae.safetensors filename in issue #1278.
VAE / Text Encoder multiselect
Current UI scans both models/VAE and models/text_encoder. Visibility in the same control does not mean every combination is compatible. Record all selected filenames.
Automatic low bits
Begin with Automatic. A GGUF or other quantized checkpoint describes diffusion-weight storage, not permission to mix arbitrary VAE and encoder files.
Possible corrupt or partial file
If one documented file fails while another complete package passes, compare publisher size/hash and redownload from that publisher. A black output alone does not guarantee corruption.
Restore one patch, control, or postprocessor
A passing base checklist turns a vague black-image report into a component boundary.
ControlNet output is black
Prove txt2img without ControlNet, then use one family-compatible control model and one preprocessor. Keep Pixel Perfect, resize mode, input image, weight, start/end, and dimensions in the checklist. Use the dedicated ControlNet diagnostic to locate the first failed gate before returning to output-stage diagnosis.
ControlNet output is stretched
Compare the control map’s aspect ratio with the output and record resize mode. The local catalog contains unresolved black/stretched reports, so this page isolates the unit; the ControlNet workflow owns exact resize and pairing guidance.
A LoRA makes output black or noisy
Prove the base checkpoint, then add one exact LoRA at a conservative documented weight. Record its base family and whether the same file fails with extensions disabled.
LayerDiffuse output looks black
Check alpha before changing the model. An earlier video transcript distinguishes a checkerboard preview composite from the separate transparent output; current LayerDiffuse behavior remains version- and mode-sensitive.
Hires. fix or ADetailer changes only the final image
Treat it as a later pass. Keep the passing base image and add exactly one postprocessor with its target dimensions and denoise settings.
An extension update changes the result
Disable every third-party extension, reproduce once, then enable one at a time. Keep extension repository, commit, Forge commit, and the first changed stage.
When only later runs break, test a sequence
The prompt is not the only variable if a clean first run works and an identical later run does not.
- Use one Forge commit, a fixed seed, batch 1, base dimensions, and no add-ons.
- Save every image and the “Model selected” object after each switch.
- Repeat the shortest failing sequence after a normal restart.
- Repeat on a separate clean install before calling it a core regression.
Do not reproduce issue #2960’s full workload first: that report still had batch 4, LoRAs, Hires. fix, and xformers. Remove those costs to identify the switch boundary.
Black on screen can be transparent in the file
Check the saved artifact before diagnosing the diffusion model.
- Open the exact PNG in a second alpha-aware editor.
- Place it over white, magenta, and checkerboard backgrounds.
- Compare pixel dimensions, file format, alpha channel, and PNG Info.
- If a preview composite and transparent output are both saved, identify which file you opened.
Capture enough to reproduce the first bad stage
Check only fields you actually saved. The result is the compact input for a useful report.
Remove usernames, private paths, prompts, tokens, remote URLs, and private images before publishing logs or Sysinfo.
Forge black-image answers
Direct answers for the long-tail questions that appear after a generation finishes with unusable output.
How do I fix a black image in Stable Diffusion WebUI Forge?
Save the failed checklist, restart once, choose the correct sd/xl/flux preset, use one documented model package, batch 1 and a fixed seed, set low bits to Automatic, remove custom launch flags, and disable Hires. fix plus every add-on. Run the same baseline twice, then restore one stage at a time.
Why is the Forge live preview black?
The live preview may use Approx NN, Approx cheap, or TAESD instead of the final Full VAE. Compare the saved final file first. If only the preview is wrong, changing the model package or final-decoder precision is premature.
Why does the preview look normal but the final Forge image is black?
That shape moves attention to Full VAE decode and later postprocessing. Disable every later stage, verify the exact VAE or FLUX autoencoder, and compare Full decode with one isolated TAESD test. It narrows the stage but does not guarantee one universal cause.
What does “invalid value encountered in cast” mean in Forge?
On the current commit, the warning occurs when Forge converts the decoded, clamped image to uint8. Non-finite values survived to that conversion. The message does not reveal whether they began in the sampler, VAE, add-on, or retained state.
Does a black image always mean the VAE is wrong?
No. A wrong or missing VAE is one proven case, especially for split FLUX packages, but black output is also reported with sampling, checkpoint switches, MPS environments, ControlNet, extensions, risky flags, and postprocessing. Isolate the first bad stage.
What does “A tensor with all NaNs was produced in VAE” mean?
That exact wording can appear in older or different WebUI code. In the current Forge commit, test_for_nans returns immediately. Capture the repository identity and commit before following advice written for another code path.
Should I use --disable-nan-check to fix black images?
No. The flag does not repair non-finite values. On the current commit, the relevant test function already returns without checking, so hiding a check cannot turn invalid image data into a valid result.
Should I add --no-half to fix black images in Forge?
Not as a first step. It broadly changes precision and can hide the stage that matters. First prove whether sampling or Full VAE decode is the boundary; then use one code- and hardware-justified comparison and record its cost.
Should I use --no-half-vae or --vae-in-fp32?
Only as an isolated decode-stage comparison after a clean baseline proves sampling passes. Record the startup VAE dtype and remove the flag if it does not change the same fixed-seed result.
Why does TAESD produce an image when Full VAE produces black?
TAESD is a different approximate decoder. The result shows the latent can be rendered through that alternate path, which focuses diagnosis on Full decode or its component. TAESD quality and resolution behavior can differ, so it is not the final repair by itself.
How do I know which VAE Forge is using?
Record the VAE / Text Encoder selections, startup VAE dtype, the console “Model selected” object, and PNG Info. For single-file models, also check whether the publisher says the VAE is baked in; for split packages, record the explicit autoencoder filename.
Why does FLUX generate a black image in Forge?
First verify the flux UI preset and one complete documented package: diffusion model, CLIP-L, one intended T5 variant, and the correct autoencoder when the package is split. Then test Automatic low bits, Queue, CPU, batch 1, no add-ons, and the same seed twice.
Does FLUX need ae.safetensors in Forge?
The maintainer specifically identified the official ae.safetensors file in issue #1278 for that user’s split FLUX setup. A bundled checkpoint may have a different contract, so follow the publisher’s package documentation rather than adding files blindly.
Should I select every T5, CLIP, and VAE file for FLUX?
No. The multiselect lists discoverable additional modules; it is not a compatibility picker. Select only the exact companion set documented for the checkpoint, and keep every filename in the checklist.
Can the wrong sd, xl, or flux preset make a black image?
A preset mismatch changes visible controls and family defaults, and issue comments report stale XL controls with a FLUX checkpoint after PNG Info transfer. Verify preset and checkpoint together before generation; treat the report as community reports, not a guaranteed cause.
Why does SDXL produce black images while SD 1.5 works?
That comparison proves the environment can generate something, not that every SDXL file is valid. Test one complete SDXL checkpoint with the xl preset, its documented VAE state, preset base dimensions, batch 1, Automatic low bits, and no add-ons.
Why do images turn black after switching checkpoints?
Reproduce a minimal A → B → A sequence after a clean restart. Keep batch 1, no Hires. fix, no LoRAs, and fixed seeds. An open issue reports switch-specific black/distorted output, but its loaded workload does not establish a universal root cause.
How do I tell whether a checkpoint or VAE file is corrupted?
A black image alone is insufficient. Compare publisher size or checksum, capture load warnings and missing keys, and test another complete documented package in the same baseline. Redownload only from the publisher or trusted original source.
Why does ControlNet make Forge output black?
Prove the same generation without ControlNet, then add one compatible unit with one preprocessor, one family-matched control model, and fixed resize/input settings. The full ControlNet workflow page handles pairing; this page only isolates the first failing boundary.
Why is my ControlNet image stretched or squashed in Forge?
Compare control-map and output aspect ratios, resize mode, Pixel Perfect state, and final dimensions. Disable Hires. fix and other units. If the base output is normal, restore the one control unit without changing the canvas.
Why does a LoRA make the Forge output black or noisy?
Test the base checkpoint first, then add one exact family-compatible LoRA at a documented weight. If it fails, repeat with third-party extensions disabled and record whether the first bad stage is conditioning, sampling, or final postprocessing.
Why does Hires. fix turn a normal image black?
Hires. fix adds later resize, VAE and sampling work. Save the passing base image, use batch 1 and a smaller target, then record whether failure begins before the second sampler or only at final decode. Route an allocation traceback to the OOM page.
Can a transparent PNG look like a black image?
Yes. Fully or partly transparent pixels can appear black on a dark background. Open the saved PNG in an alpha-aware editor and place it over a bright color. Do not change precision until you inspect the alpha channel.
Why is the saved PNG black when the Forge preview looked correct?
Open the exact file elsewhere and compare alpha and PNG Info. If both viewers show black, the failure happened by final conversion/save; if only Forge’s gallery differs, preserve the file and troubleshoot the viewer boundary.
Why does Forge output noise instead of a black image?
Use the correct preset, one documented component set, base dimensions, fixed seed, and no conditioning add-ons. Noise that never resolves can indicate a different model-contract or sampling problem than a final decode that turns an otherwise plausible preview black.
Why are only some images in a batch black?
Reduce to batch 1 and run the exact seeds individually. A mixed batch is useful a sign of intermittent numeric or state behavior, but it does not identify VAE, sampler, hardware, or extension without single-seed reproduction.
What should I do if black images started after an update?
Keep the last passing commit and first failing commit, reproduce on a clean extension-free install, and use the same model files and checklist. Rollback can restore work, but a useful regression report still needs the smallest changed commit range.
What should I include in a Forge black-image bug report?
Include Forge identity and commit, install route, GPU/driver/Torch, preset, checkpoint hash, every VAE/encoder, launch flags, complete parameters, add-ons, first bad stage, exact warning, saved output, last passing checklist, clean-install result, and a minimal repeat sequence.