MonoGame/MonoGame · error · ArgumentException

nearPlaneDistance >= farPlaneDistance

Error message

nearPlaneDistance >= farPlaneDistance

What it means

Thrown as ArgumentException by Matrix.CreatePerspective when nearPlaneDistance is greater than or equal to farPlaneDistance. The near plane must be strictly in front of the far plane for a valid frustum.

Source

Thrown at MonoGame.Framework/Matrix.cs:927

        /// </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;
        }

        /// <summary>
        /// Creates a new projection <see cref="Matrix"/> for perspective view with field of view.
        /// </summary>

View on GitHub (pinned to 1d71bbd0ff)

Solutions

1. Ensure nearPlaneDistance < farPlaneDistance (e.g. near=0.1, far=1000).
2. Swap the arguments if they were reversed.
3. Validate and clamp near to be strictly less than far before calling.

Example fix

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

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

if (nearPlaneDistance >= farPlaneDistance)
    throw new ArgumentException("near must be less than far.");
Matrix.CreatePerspective(w, h, nearPlaneDistance, farPlaneDistance, out proj);

When it happens

Trigger: Passing near >= far (e.g. near=10, far=10, or near=100, far=50); swapped near/far arguments; equal values from config.

Common situations: Swapping near and far when calling; config typos making near larger than far; dynamically computed planes that cross.

Related errors

• nearPlaneDistance <= 0
• farPlaneDistance <= 0
• 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/bc689e1e1bb7b4d8. Report an issue: GitHub.