AUTOMATIC1111/stable-diffusion-webui · critical · NansException

A tensor with NaNs was produced. Use --disable-nan-check com

Error message

A tensor with NaNs was produced. Use --disable-nan-check commandline argument to disable this check.

What it means

NansException raised by modules.devices debug-on-exception hooks (torch autograd anomaly detection / nan_and_inf detection installed per where='unet'/'vae') when a forward or backward pass produced NaN/Inf activations. The message tail advertises --disable-nan-check as the escape hatch; the head is context-specific: unet NaNs suggest fp16 precision issues or an unsupported half-precision GPU, vae NaNs suggest the VAE encoding/decoding overflowed in half precision.

Source

Thrown at modules/devices.py:265

        return

    if where == "unet":
        message = "A tensor with NaNs was produced in Unet."

        if not shared.cmd_opts.no_half:
            message += " This could be either because there's not enough precision to represent the picture, or because your video card does not support half type. Try setting the \"Upcast cross attention layer to float32\" option in Settings > Stable Diffusion or using the --no-half commandline argument to fix this."

    elif where == "vae":
        message = "A tensor with NaNs was produced in VAE."

        if not shared.cmd_opts.no_half and not shared.cmd_opts.no_half_vae:
            message += " This could be because there's not enough precision to represent the picture. Try adding --no-half-vae commandline argument to fix this."
    else:
        message = "A tensor with NaNs was produced."

    message += " Use --disable-nan-check commandline argument to disable this check."

    raise NansException(message)


@lru_cache
def first_time_calculation():
    """
    just do any calculation with pytorch layers - the first time this is done it allocates about 700MB of memory and
    spends about 2.7 seconds doing that, at least with NVidia.
    """

    x = torch.zeros((1, 1)).to(device, dtype)
    linear = torch.nn.Linear(1, 1).to(device, dtype)
    linear(x)

    x = torch.zeros((1, 1, 3, 3)).to(device, dtype)
    conv2d = torch.nn.Conv2d(1, 1, (3, 3)).to(device, dtype)
    conv2d(x)

View on GitHub (pinned to 82a973c043)

Solutions

For VAE NaNs: add --no-half-vae (or set Settings -> Stable Diffusion -> 'Upcast cross attention layer to float32')
For UNet NaNs: run with --no-half to compute in fp32, or enable upcast of cross attention layers
Update PyTorch/CUDA and GPU drivers so fp16 kernels for your card are correct; on unsupported cards use --precision full --no-half
As a last resort to keep the pipeline running (black-image risk): launch with --disable-nan-check

Example fix

# before
./webui.sh

# after (typical fp16 VAE failure)
./webui.sh --no-half-vae
# or full precision:
./webui.sh --no-half

Defensive patterns

Strategy: fallback

Validate before calling

# detect fp16 capability before running with half precision
import torch
fp16_safe = torch.cuda.is_available() and torch.cuda.get_device_capability(0) >= (7, 0)
# pass --no-half-vae / --no-half in launch args when not fp16_safe

Type guard

def gpu_supports_fp16() -> bool:
    return torch.cuda.is_available() and torch.cuda.get_device_capability(0) >= (7, 0)

Try / catch

from modules.devices import NansException
try:
    processed = processing.process_images(p)
except NansException as e:
    if 'VAE' in str(e):
        enable_no_half_vae_and_rerun(p)   # fallback precision route
    else:
        raise

Prevention

Use --no-half-vae on setups that hit VAE NaNs; --no-half for UNet NaNs
Update PyTorch/CUDA when a new GPU arch misbehaves in fp16
Avoid --disable-nan-check except for debugging; it masks black-image outputs
Watch for NaN warnings in the console log during first generations after config changes

When it happens

Trigger: Generating (txt2img/img2img) on a GPU that poorly supports fp16 (older cards, some MX/Intel/iGPUs, certain driver versions); fp16 overflow in the UNet at high resolutions or with --xformers variants; VAE decode NaNs at 4x8x upscaling resolutions on fp16 VAEs; also genuinely diverging training in the train tab. Any of these while the nan check is active (default; disabled only via --disable-nan-check).

Common situations: First runs on unsupported/newer GPUs (e.g. when a new arch lacked proper fp16 kernels); SDXL/Flux at high res with fp16 VAE; corrupted or incompatible checkpoints; batch-size/memory pressure causing garbage computation; users who just want generation to continue disabling the check and shipping black images.

Related errors

AI-assisted analysis of AUTOMATIC1111/stable-diffusion-webui@82a973c043 (2026-08-14). Data as JSON: /api/errors/639bd1bd452afce7. Report an issue: GitHub.