FORGEFIELD GUIDE
DIAGNOSE BY STAGE · CHANGE ONE VARIABLE

Stable Diffusion WebUI Forge Troubleshooting

Start with the last thing Forge completed—not the most alarming message on screen. Preserve the console, isolate one stage, and make the smallest test that can disprove a cause.

Evidence checked24 Aug 2026Inspected main commitdfdcbabScopeOriginal Forge only
FIRST 10 MINUTES

Do not repair the evidence away.

Before updating, reinstalling packages, deleting a virtual environment, or adding flags, capture the Forge commit, launch command, exact action and last complete traceback.

Choose a symptom Build a report packet
  1. 01
    Freeze the state

    Do not update Forge, extensions, drivers or model files yet.

  2. 02
    Save the console

    Copy from startup through the failure, including the first traceback line.

  3. 03
    Name the last completed stage

    Process, server, model load, sampling, decode or save.

  4. 04
    Remove one layer

    Use a fixed seed and change only the suspected extension, model or setting.

01 · SYMPTOM ROUTER

What failed first?

Choose the first observable failure. The router gives you one safe test and the evidence that makes the next step useful.

Choose a Forge symptom
SELECTED ROUTEStart / connect

The process closes, pauses at “Press any key”, or the browser cannot reach the local URL.

First safe test
Keep the console open and read the last complete error. Check whether the Forge process is still running before changing the browser or port.
Capture
Startup log, local URL, commit, launch arguments, Python/Torch lines, and the last traceback.
Open this route
02 · PIPELINE CHECK

Find the last completed stage.

A browser error is not a root cause if the Python process already crashed. A black final file is not the same failure as a model that never loaded.

  1. 01
    Process

    Did the Forge process stay open?

    If it closed, the browser message is secondary. Diagnose the last console error.
  2. 02
    Server

    Did the console print a local URL?

    If yes, test that exact address. If no, startup did not reach the web server.
  3. 03
    Model load

    Did the requested model finish loading?

    Separate runtime problems from corrupted, incompatible, or incomplete model assets.
  4. 04
    Sampling

    Did progress begin and complete?

    An OOM during sampling is different from a crash while loading weights or decoding the VAE.
  5. 05
    Decode / save

    Was the final file valid?

    A good preview followed by a black final image points later in the pipeline than a failure at step zero.
03 · CLEAN BASELINE

A fresh install is a comparison, not a reset button.

The official README says a fresh reinstall helps when a problem cannot be reproduced. Keep the broken folder so the comparison can tell you what changed.

Read the dated official guidance ↗
  1. 1
    Preserve the failing install.

    Record its commit, launch arguments, extension list and model hash. Do not overwrite it.

  2. 2
    Make a separate clean folder.

    Use the official package or repository route. Do not copy the old virtual environment, config or extensions into it.

  3. 3
    Prove core generation first.

    Use one trusted model, its intended preset, a fixed seed, batch size 1, and no LoRA, ControlNet, Hires. fix or third-party extension.

  4. 4
    Compare like with like.

    Keep the model hash, prompt, seed, dimensions, sampler and steps identical. Save both full logs.

  5. 5
    Add one layer at a time.

    Model companions, then LoRA, then ControlNet, then Hires. fix, then extensions. Stop when the symptom returns.

OLD FAILS · CLEAN WORKS

Local state, dependency drift, configuration or an extension is implicated.

BOTH FAIL IDENTICALLY

Inspect the shared model, inputs, hardware/runtime and exact Forge build before blaming accumulated state.

ONLY ONE COMMIT FAILS

You now have the beginning of a regression report: last good, first bad and a controlled reproduction.

04 · FULL SYMPTOM GUIDE

Minimal tests by failure type

These tests are intentionally narrow. They identify a branch; they do not promise one universal fix for every machine.

Connection errored out · Error 1006 · Read timed out

Confirm whether the Forge process is alive, then use the last console error. The browser phrase alone is not a diagnosis.

Press any key to continue · console closes in a flash

Forge exited. Start it from a terminal or keep the launcher window open so the complete error remains visible.

CPUAllocator · Killed · Segmentation Fault · core dumped

Route to system-memory evidence: failure stage, RAM, swap, free disk and model load. The official 2024 swap guidance is dated.

MetadataIncompleteBuffer · PytorchStreamReader failed

Identify the file named near the error, compare its size or published hash, and re-download it from the original publisher before changing Python packages.

Torch not compiled with CUDA enabled · subprocess-exited-with-error

Route to the installation environment. Capture Python, Torch, device and the official install path instead of bypassing the failed check.

SSL: CERTIFICATE_VERIFY_FAILED

Capture the requested URL, system clock, proxy or VPN and certificate error. Use an official manual-download route when available; do not disable TLS verification globally.

01VERIFIED

Forge will not start or the UI disconnects

Separate browser from process. If the console closed, says “Press any key”, or never printed Running on local URL, the server is not available. If the process remains open, test the exact URL and port it printed.

  • Save the last traceback, not only “Connection errored out”.
  • Record whether the failure happened before or after model loading.
  • For CPUAllocator, Killed, timeouts and model-load stalls, inspect RAM and system swap evidence—but treat the official 2024 swap advice as dated, not a universal diagnosis.
Open the complete startup decision tree →Official connection troubleshooting ↗
02VERIFIED

Python, pip, Torch or accelerator error

Prove the runtime matches the install route. Capture the Python version, Torch build and the device line. “Torch not compiled with CUDA enabled” is an environment mismatch in the official guide, not a generation setting.

  • Do not use --skip-torch-cuda-test merely to hide a real CUDA failure.
  • A missing module inside an extension traceback may belong to that extension; repeat with all extensions disabled before repairing core packages.
  • Test manual package changes only after a separate clean install establishes that the packaged environment is the problem.
Open the Python, Torch and CUDA diagnostic guide →
03VERIFIED

CUDA OOM, RAM exhaustion, freeze or crash

Name the memory stage. Loading weights, sampling, Hires. fix, VAE decode and repeated generations have different peaks. Reduce one driver at a time: batch, dimensions, second pass, extra networks, then model size or format.

  • For FLUX, leave VRAM for computation; the maintainer explicitly warns against setting GPU Weight to maximum.
  • Record system RAM as well as VRAM. A quantized model file does not guarantee that the whole workflow fits in GPU memory.
  • If usage rises across identical runs, report the run count and memory after each run rather than calling it a leak from one observation.
Open the out-of-memory diagnostic →Tune a workload that already passes →Official performance-reporting method ↗
04COMMUNITY-REPORTED

Black, blank, stretched or corrupted output

Test the final decode separately. Use a fixed seed with the base model, intended preset and automatic or known-good VAE. Disable LoRAs, ControlNet, Hires. fix and custom precision flags for the comparison.

  • If the preview is good until the final step, record that: it narrows the failure to a later stage.
  • If the base generation is correct, add the VAE, Hires. fix and ControlNet back one at a time.
  • Do not recommend --no-half or --no-half-vae blindly; first capture the hardware, warning and model family that justify a precision test.
Open the black, blank, and distorted-output diagnostic →
05VERIFIED

Model or LoRA missing, rejected or ignored

Identify the asset before moving it. A checkpoint, UNet, LoRA, VAE, CLIP and T5 file are not interchangeable. Confirm the base-model family and any companion modules from the original model page.

  • Refresh the correct selector after placing the file in its correct folder.
  • Use a source-published hash when available; re-download from the original publisher if the read error indicates corruption.
  • For a LoRA, save the patch log and compare the same seed at zero versus a documented weight on a compatible base model.
Run the complete model and LoRA diagnostic →Open the model file map →
06VERIFIED

Missing tab, Gradio error or extension conflict

Disable; do not delete. Current Forge defines --disable-all-extensions. If core Forge works with that argument, use binary search: enable half, reproduce, then halve the failing group.

  • Capture the extension repository, branch and commit—not only its display name.
  • An extension appearing in a list or folder does not prove compatibility with the current Forge/Gradio build.
  • Check the official temporary replacement list for maintained Forge-specific forks.
Run the complete extension conflict diagnostic →Verify the launch argument ↗Official extension replacement list ↗
07COMMUNITY-REPORTED

ControlNet missing, ineffective or malformed

Prove one unit end to end. The base checkpoint family, ControlNet model and preprocessor must describe the same job. Confirm that the preprocessor produces a meaningful map before judging the final image.

  • Test one unit, no LoRA and no Hires. fix; compare enabled versus disabled with the same seed.
  • Record weight, guidance start/end, resize mode and dimensions.
  • Because Union and FLUX support changed across dated builds, cite the exact Forge commit instead of saying ControlNet “works” or “does not work” globally.
Run the ControlNet diagnostic →
08VERIFIED

Behavior changed after an update

Build a matched before/after pair. Use the same model hash, seed, prompt, dimensions, sampler, settings and extension state. Capture the last good and first bad Forge commits and both full logs.

  • Do not update extensions, drivers and Forge together while diagnosing.
  • Reproduce in a separate clean current install before attributing the change to the update.
  • If rollback is necessary for work, keep the known-good folder separate and still report the controlled comparison.
Run the update regression diagnostic →
05 · ESCALATION DATA

Send a reproducible report, not a screenshot of the last line.

Forge can expose a Sysinfo download under Settings → Sysinfo. It includes paths, launch arguments, package versions, configuration and extension metadata, so review it before posting.

Privacy check

Remove credentials, tokens and personal path details where possible without deleting the error context. Forge masks its own Gradio/API auth argument, but you should still inspect the whole file.

INCIDENT TEMPLATEPlain text · nothing is uploaded
Forge troubleshooting report

PROJECT
- Repository: lllyasviel/stable-diffusion-webui-forge (original)
- Forge commit / version:
- Last known-good commit (if any):
- Install route: official one-click / Git clone / other

SYSTEM
- OS and version:
- GPU and VRAM:
- System RAM:
- Python version:
- Torch build and accelerator line:
- Driver version:

REPRODUCTION
- Exact action:
- Expected result:
- Observed result:
- Model filename and hash:
- Preset / model family:
- Companion VAE / CLIP / T5 files:
- Prompt / seed / dimensions / sampler / steps:
- Hires. fix / batch / ControlNet / LoRAs:
- Launch arguments:

ISOLATION
- Result with --disable-all-extensions:
- Result in a separate fresh install:
- Smallest setting or extension set that reproduces it:

EVIDENCE
- Last complete traceback:
- Full console log attached: yes / no
- Sysinfo attached after privacy review: yes / no
- Screenshots or output files attached: yes / no
UI PATHSettings → Sysinfo → Download system info
CLI ALTERNATIVE--dump-sysinfo writes limited Sysinfo and exits

Verified in current main source: Sysinfo UI ↗ · fields and auth masking ↗ · CLI argument ↗

06 · AVOID FALSE FIXES

Changes that destroy the diagnosis

  • Updating everything at onceYou lose the boundary between last good and first bad.
  • Stacking copied command-line flagsA warning may disappear while the unsupported runtime remains.
  • Force-reinstalling Python packages firstYou can create dependency drift before proving Forge itself is at fault.
  • Deleting extensions or the failing folderDisable and preserve them so the conflict remains reproducible.
  • Calling one crash a memory leakTrack identical runs and memory growth before making the claim.
  • Using a random patched archiveModified core files make support status and provenance unknowable.
07 · COMMON QUESTIONS

Forge troubleshooting FAQ

Short answers to the questions users most often type when a local Forge workflow fails.

Why is Stable Diffusion WebUI Forge not opening?

Read the console before the browser. If the process closed or never printed a local URL, troubleshoot the last startup traceback. If it stayed open and printed a URL, test that exact address and record the port.

What does “Connection errored out” mean in Forge?

It means the browser lost its connection to the Forge process; it does not identify one cause by itself. Check whether the process is still alive and use the last console lines to distinguish memory pressure, a crash, a timeout, or a networking problem.

How do I fix “Torch not compiled with CUDA enabled” in Forge?

Treat it as an installation or runtime mismatch, not a prompt-setting problem. Record the installation route, GPU, Python, Torch build and accelerator line, then compare them with the official installation path. Do not merely skip the CUDA test.

How do I troubleshoot CUDA out of memory in Forge?

First identify the stage that ran out of memory. Reproduce with batch size 1, no Hires. fix, ControlNet or LoRAs, and smaller model-family-appropriate dimensions. For FLUX, do not set GPU Weight to its maximum because inference still needs free VRAM.

Why does Forge generate black images?

A black result can come from different stages. Repeat a fixed seed with the correct preset and base model, automatic or known-good VAE, no LoRAs, ControlNet, Hires. fix or custom precision flags. Record whether the preview was valid before the final decode changed.

Why is my model or LoRA not showing in Forge?

Verify that the file is in the folder for its actual asset type, refresh the corresponding list, and confirm its base-model family and required companion files. A LoRA should be tested against a working base model while the load log is visible.

How do I start Forge without extensions?

Temporarily add `--disable-all-extensions` to the launch arguments. Current Forge code defines that argument to prevent all extensions from running. Remove it after the isolation test; there is no need to delete extension folders.

Why is an extension tab missing in Forge?

The extension may have failed during preload, target a different Gradio or Forge generation, or conflict with another extension. Test with all extensions disabled, then enable one half at a time. Check the dated official extension replacement list before assuming an A1111 extension is compatible.

Why does ControlNet do nothing in Forge?

Test one ControlNet unit alone and verify the base-model family, ControlNet model, preprocessor output, control weight and guidance range. A model merely appearing in a shared folder does not prove that the current Forge build supports that model and family together.

What should I do if Forge broke after an update?

Freeze the environment and capture the current commit and full log. Compare the exact same seed, model hash and settings on the last known-good build and a separate clean current install. That comparison distinguishes a regression from accumulated local state.

What information belongs in a Forge bug report?

Include the original repository identity, Forge commit, install route, OS, GPU and memory, Python and Torch versions, launch arguments, exact model files and settings, minimal reproduction, extension-disabled result, clean-install result, full log and Sysinfo after a privacy review.

08 · EVIDENCE LEDGER

What this guide can prove

Official source and code establish available controls and maintainer guidance. Community reports establish recurring user symptoms only; they do not prove universal bugs.

OFFICIALREADME and fresh-install ruleOFFICIAL · DATED 2024Connection / swap troubleshootingOFFICIAL · TEMPORARYExtension replacement listOFFICIALControlled performance reportsSOURCE CODEExtension isolation and Sysinfo argsSOURCE CODESysinfo contents and maskingOFFICIAL ISSUECertificate failure report and context
Community symptom set reviewed for this page (10 reports)
AuthorForge Field Guide editorial teamReviewerTechnical editorial reviewUpdated24 Aug 2026