MonoGame/MonoGame · error · ArgumentException

farPlaneDistance <= 0

Error message

farPlaneDistance <= 0

What it means

Thrown as ArgumentException by Matrix.CreatePerspective when farPlaneDistance is less than or equal to zero. The far plane must be positive (float.PositiveInfinity is explicitly allowed by the API).

Source

Thrown at MonoGame.Framework/Matrix.cs:923

        }

        /// <summary>
        /// Creates a new projection <see cref="Matrix"/> for perspective view.
        /// </summary>
        /// <param name="width">Width of the viewing volume.</param>
        /// <param name="height">Height of the viewing volume.</param>
        /// <param name="nearPlaneDistance">Distance to the near plane.</param>
        /// <param name="farPlaneDistance">Distance to the far plane, or <see cref="float.PositiveInfinity"/>.</param>
        /// <param name="result">The new projection <see cref="Matrix"/> for perspective view as an output parameter.</param>
        public static void CreatePerspective(float width, float height, float nearPlaneDistance, float farPlaneDistance, out Matrix result)
        {
            if (nearPlaneDistance <= 0f)
		    {
		        throw new ArgumentException("nearPlaneDistance <= 0");
		    }
		    if (farPlaneDistance <= 0f)
		    {
		        throw new ArgumentException("farPlaneDistance <= 0");
		    }
		    if (nearPlaneDistance >= farPlaneDistance)
		    {
		        throw new ArgumentException("nearPlaneDistance >= farPlaneDistance");
		    }

            var negFarRange = float.IsPositiveInfinity(farPlaneDistance) ? -1.0f : farPlaneDistance / (nearPlaneDistance - farPlaneDistance);

            result.M11 = (2.0f * nearPlaneDistance) / width;
            result.M12 = result.M13 = result.M14 = 0.0f;
            result.M22 = (2.0f * nearPlaneDistance) / height;
            result.M21 = result.M23 = result.M24 = 0.0f;            
            result.M33 = negFarRange;
            result.M31 = result.M32 = 0.0f;
            result.M34 = -1.0f;
            result.M41 = result.M42 = result.M44 = 0.0f;
            result.M43 = nearPlaneDistance * negFarRange;
        }

View on GitHub (pinned to 1d71bbd0ff)

Solutions

1. Set farPlaneDistance to a large positive value (e.g. 1000f) or float.PositiveInfinity.
2. Validate and clamp far to a positive value before calling.
3. Ensure config deserialization does not leave far at 0.

Example fix

// before
Matrix.CreatePerspective(w, h, 0.1f, 0f, out proj); // far=0

// after
Matrix.CreatePerspective(w, h, 0.1f, 1000f, out proj);

float far = farPlaneDistance <= 0f ? 1000f : farPlaneDistance;
Matrix.CreatePerspective(w, h, nearPlaneDistance, far, out proj);

When it happens

Trigger: Passing farPlaneDistance = 0, a negative value, or an unset value to CreatePerspective.

Common situations: Defaulting far to 0; computing far as a difference that goes negative; deserialized camera config with missing far value.

Related errors

• nearPlaneDistance <= 0
• nearPlaneDistance >= farPlaneDistance
• fieldOfView <= 0 or >= PI
• Handling for the run behavior {0} is not implemented.
• Cannot Add Same Component Multiple Times

AI-assisted analysis of MonoGame/MonoGame@1d71bbd0ff (2026-08-13). Data as JSON: /api/errors/4e3b330977437ada. Report an issue: GitHub.