bevyengine/bevy · error · ViewportConversionError

computed coordinate beyond `Camera`'s near plane

Error message

computed coordinate beyond `Camera`'s near plane

What it means

ViewportConversionError::BeyondNear: the world-space position being converted lies behind or exactly on the camera's near clipping plane, so projecting it to viewport (screen) coordinates is undefined and the conversion returns an error instead of garbage coordinates.

Source

Thrown at crates/bevy_camera/src/camera.rs:345

/// Error returned when a conversion between world-space and viewport-space coordinates fails.
///
/// See [`world_to_viewport`][Camera::world_to_viewport] and [`viewport_to_world`][Camera::viewport_to_world].
#[derive(Debug, Eq, PartialEq, Copy, Clone, Error)]
pub enum ViewportConversionError {
    /// The pre-computed size of the viewport was not available.
    ///
    /// This may be because the `Camera` was just created and `camera_system` has not been executed
    /// yet, or because the [`RenderTarget`] is misconfigured in one of the following ways:
    ///   - it references the [`PrimaryWindow`](RenderTarget::Window) when there is none,
    ///   - it references a [`Window`](RenderTarget::Window) entity that doesn't exist or doesn't actually have a `Window` component,
    ///   - it references an [`Image`](RenderTarget::Image) that doesn't exist (invalid handle),
    ///   - it references a [`TextureView`](RenderTarget::TextureView) that doesn't exist (invalid handle).
    #[error("pre-computed size of viewport not available")]
    NoViewportSize,
    /// The computed coordinate was beyond the `Camera`'s near plane.
    ///
    /// Only applicable when converting from world-space to viewport-space.
    #[error("computed coordinate beyond `Camera`'s near plane")]
    PastNearPlane,
    /// The computed coordinate was beyond the `Camera`'s far plane.
    ///
    /// Only applicable when converting from world-space to viewport-space.
    #[error("computed coordinate beyond `Camera`'s far plane")]
    PastFarPlane,
    /// The Normalized Device Coordinates could not be computed because the `camera_transform`, the
    /// `world_position`, or the projection matrix defined by [`Projection`](super::projection::Projection)
    /// contained `NAN` (see [`world_to_ndc`][Camera::world_to_ndc] and [`ndc_to_world`][Camera::ndc_to_world]).
    #[error("found NaN while computing NDC")]
    InvalidData,
}

/// The defining [`Component`] for camera entities,
/// storing information about how and what to render through this camera.
///
/// The [`Camera`] component is added to an entity to define the properties of the viewpoint from
/// which rendering occurs. It defines the position of the view to render, the projection method

View on GitHub (pinned to 396ca72708)

Solutions

1. Move the point in front of the camera (distance > near clip)
2. Increase the near plane distance if points legitimately sit very close
3. Treat entities behind the camera as off-screen and skip them

When it happens

Trigger: Thrown at crates/bevy_camera/src/camera.rs:345 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of bevyengine/bevy@396ca72708 (2026-08-20). Data as JSON: /api/errors/0cffec3211efd8b7. Report an issue: GitHub.