What causes "Failed to load HDRI environment:" in moeru-ai/airi?

Verify skyBoxSrc returns 200 with CORS headers (open it directly in the browser)

Failed to load HDRI environment:

Error message

Failed to load HDRI environment:

What it means

loadEnvironment turns the HDRI/sky box source into a PMREM environment texture, assigns it to scene.environment (and scene.background when asBackground), then emits skyBoxReady with the irradiance SH. Any throw — fetch failure, RGBE parse error, PMREM/WebGL failure — is caught and warned; the scene keeps running with no environment map, leaving PBR materials unlit or flat.

Source

Thrown at packages/stage-ui-three/src/components/Environment/SkyBox.vue:143

      renderer as WebGLRenderer,
      cubeRT,
    )

    // PBR IBL
    environment.value = hdrTex
    const scn = scene.value as Scene
    scn.environment = rt.texture // drives PBR materials (Standard/Physical)
    if (props.asBackground)
      scn.background = rt.texture // optional: also show as background
    // r152+: background controls (no-ops on older versions)
    scn.backgroundBlurriness = props.backgroundBlurriness
    scn.backgroundIntensity = props.backgroundIntensity

    // emit irrSH for NPR IBL
    emit('skyBoxReady', { irrSH: probe.sh })
  }
  catch (error) {
    console.warn('Failed to load HDRI environment:', error)
  }
}

// Usage in your component
onMounted(async () => {
  // load environment from sky box (default or user input)
  await loadEnvironment(props.skyBoxSrc)

  // hot switch: react to sky box change
  watch(
    // Actually we can also let user set background blurriness or intensity
    // TODO: maybe we can open more options for users regarding to the settings of the background in the future
    () => [props.skyBoxSrc],
    ([skyBoxSrc]) => {
      loadEnvironment(skyBoxSrc as string)
    },
    { deep: false },
  )

View on GitHub (pinned to 677329427f)

Solutions

Verify skyBoxSrc returns 200 with CORS headers (open it directly in the browser)
Use a valid equirectangular .hdr file; convert other formats first
Downscale large HDRIs for mobile targets to avoid PMREM OOM
Set a fallback scene.environment (e.g. a neutral color) in the catch so PBR is not unlit
Check for WebGL context loss if loading previously worked

Defensive patterns

Strategy: try-catch

Validate before calling

if (!props.skyBoxSrc) return // nothing to load; keep default lighting

Try / catch

try {
  const scn = scene.value as Scene
  scn.environment = rt.texture
  if (props.asBackground) scn.background = rt.texture
  emit('skyBoxReady', { irrSH: probe.sh })
}
catch (error) {
  console.warn('Failed to load HDRI environment:', error)
  // scene continues without IBL; optionally set a neutral fallback environment here
}

Prevention

Serve .hdr assets over CORS-enabled URLs and verify 200 responses
Use valid equirectangular HDR files; other formats fail at parse
Downscale HDRIs for mobile to avoid PMREM OOM
Set a fallback environment in the catch so PBR materials are never unlit

When it happens

Trigger: skyBoxSrc returning 404 or CORS-blocked; the file is not a valid equirectangular .hdr; PMREM generation failing on a lost or limited WebGL context; a huge HDR exhausting memory on mobile.

Common situations: Typo in the skyBoxSrc path; assets moved without updating config; local or CORS-less hosting; 8K HDRs on mobile devices.

Related errors

AI-assisted analysis of moeru-ai/airi@677329427f (2026-08-18). Data as JSON: /api/errors/5d410d113f133879. Report an issue: GitHub.