THREE.CubeCamera.updateCoordinateSystem(): Invalid coordinat

Error message

THREE.CubeCamera.updateCoordinateSystem(): Invalid coordinate system: ${coordinateSystem}

What it means

Thrown by CubeCamera.updateCoordinateSystem() when the active coordinate system is neither WebGLCoordinateSystem nor WebGPUCoordinateSystem. The method orients the six face cameras (PX/NX/PY/NY/PZ/NZ) differently for each system; an unknown value has no valid orientation preset. The value normally comes from renderer.coordinateSystem, set automatically when CubeCamera.update(renderer, scene) detects a change.

Source

Thrown at src/cameras/CubeCamera.js:157

			cameraNX.up.set( 0, - 1, 0 );
			cameraNX.lookAt( 1, 0, 0 );

			cameraPY.up.set( 0, 0, 1 );
			cameraPY.lookAt( 0, 1, 0 );

			cameraNY.up.set( 0, 0, - 1 );
			cameraNY.lookAt( 0, - 1, 0 );

			cameraPZ.up.set( 0, - 1, 0 );
			cameraPZ.lookAt( 0, 0, 1 );

			cameraNZ.up.set( 0, - 1, 0 );
			cameraNZ.lookAt( 0, 0, - 1 );

		} else {

			throw new Error( 'THREE.CubeCamera.updateCoordinateSystem(): Invalid coordinate system: ' + coordinateSystem );

		}

		for ( const camera of cameras ) {

			this.add( camera );

			camera.updateMatrixWorld();

		}

	}

	/**
	 * Calling this method will render the given scene with the given renderer
	 * into the cube render target of the camera.
	 *
	 * @param {(Renderer|WebGLRenderer)} renderer - The renderer.

View on GitHub (pinned to da05705fa3)

Solutions

Use a standard renderer: WebGLRenderer (WebGLCoordinateSystem) or WebGPURenderer (WebGPUCoordinateSystem) so renderer.coordinateSystem is always valid.
If you built a custom renderer, set its coordinateSystem property to either THREE.WebGLCoordinateSystem or THREE.WebGPUCoordinateSystem before calling cubeCamera.update().
In tests, ensure the mock renderer exposes a valid coordinateSystem field rather than leaving it undefined.
Avoid manually assigning cubeCamera.coordinateSystem to arbitrary integers; let CubeCamera.update() sync it from the renderer.

Example fix

// before: custom renderer with no coordinateSystem
cubeCamera.update(myRenderer, scene); // myRenderer.coordinateSystem === undefined

// after: expose a valid coordinate system on the renderer
myRenderer.coordinateSystem = THREE.WebGLCoordinateSystem;
cubeCamera.update(myRenderer, scene);

Defensive patterns

Strategy: validation

Validate before calling

import { WebGLCoordinateSystem, WebGPUCoordinateSystem } from 'three';

function assertCoordinateSystem(renderer) {
  const cs = renderer.coordinateSystem;
  if (cs !== WebGLCoordinateSystem && cs !== WebGPUCoordinateSystem) {
    throw new Error(`renderer.coordinateSystem must be WebGL/WebGPU, got ${cs}`);
  }
}

// before rendering with a CubeCamera
assertCoordinateSystem(renderer);
cubeCamera.update(renderer, scene);

Type guard

import { WebGLCoordinateSystem, WebGPUCoordinateSystem } from 'three';

function hasValidCoordinateSystem(renderer) {
  const cs = renderer && renderer.coordinateSystem;
  return cs === WebGLCoordinateSystem || cs === WebGPUCoordinateSystem;
}

Prevention

Always source coordinateSystem from a real WebGLRenderer or WebGPURenderer.
In tests, set mockRenderer.coordinateSystem to a valid constant before calling update().
Never manually assign cubeCamera.coordinateSystem to arbitrary integers.

When it happens

Trigger: Calling cubeCamera.update(renderer, scene) where renderer.coordinateSystem is null, undefined, or a custom value. Also manually invoking updateCoordinateSystem() after assigning cubeCamera.coordinateSystem to a non-standard constant, or passing a fake/mock renderer object whose coordinateSystem field is unset.

Common situations: Using a custom renderer abstraction that does not expose coordinateSystem. Passing a stub renderer in tests. Migrating between WebGL and WebGPU and leaving a stale/null coordinateSystem. Forking three.js and introducing a third coordinate system without extending this switch.

Related errors

AI-assisted analysis of mrdoob/three.js@da05705fa3 (2026-08-12). Data as JSON: /api/errors/3519cdea11f4989e. Report an issue: GitHub.