From bd4c960f26176e59ab056351bdd672cf6341835b Mon Sep 17 00:00:00 2001
From: Chris Russell <8494645+chescock@users.noreply.github.com>
Date: Wed, 4 Jun 2025 12:39:54 -0400
Subject: [PATCH] Mention `Option` and `When` in the error message for a
 failing system parameter (#19490)

# Objective

Help users discover how to use `Option<T>` and `When<T>` to handle
failing parameters.

## Solution

Have the error message for a failed parameter mention that `Option<T>`
and `When<T>` can be used to handle the failure.

## Showcase

```
Encountered an error in system `system_name`: Parameter `Res<ResourceType>` failed validation: Resource does not exist
If this is an expected state, wrap the parameter in `Option<T>` and handle `None` when it happens, or wrap the parameter in `When<T>` to skip the system when it happens.
```
---
 crates/bevy_ecs/src/system/system.rs          | 2 +-
 crates/bevy_ecs/src/system/system_param.rs    | 8 ++++++--
 crates/bevy_ecs/src/system/system_registry.rs | 2 +-
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/crates/bevy_ecs/src/system/system.rs b/crates/bevy_ecs/src/system/system.rs
index 408a0589fd..edb2ead9cd 100644
--- a/crates/bevy_ecs/src/system/system.rs
+++ b/crates/bevy_ecs/src/system/system.rs
@@ -456,7 +456,7 @@ mod tests {
         let result = world.run_system_once(system);
 
         assert!(matches!(result, Err(RunSystemError::InvalidParams { .. })));
-        let expected = "System bevy_ecs::system::system::tests::run_system_once_invalid_params::system did not run due to failed parameter validation: Parameter `Res<T>` failed validation: Resource does not exist";
+        let expected = "System bevy_ecs::system::system::tests::run_system_once_invalid_params::system did not run due to failed parameter validation: Parameter `Res<T>` failed validation: Resource does not exist\nIf this is an expected state, wrap the parameter in `Option<T>` and handle `None` when it happens, or wrap the parameter in `When<T>` to skip the system when it happens.";
         assert_eq!(expected, result.unwrap_err().to_string());
     }
 }
diff --git a/crates/bevy_ecs/src/system/system_param.rs b/crates/bevy_ecs/src/system/system_param.rs
index df14530f48..bc5fe20302 100644
--- a/crates/bevy_ecs/src/system/system_param.rs
+++ b/crates/bevy_ecs/src/system/system_param.rs
@@ -151,7 +151,7 @@ use variadics_please::{all_tuples, all_tuples_enumerated};
 /// let mut world = World::new();
 /// let err = world.run_system_cached(|param: MyParam| {}).unwrap_err();
 /// let expected = "Parameter `MyParam::foo` failed validation: Custom Message";
-/// assert!(err.to_string().ends_with(expected));
+/// assert!(err.to_string().contains(expected));
 /// ```
 ///
 /// ## Builders
@@ -2557,7 +2557,11 @@ impl Display for SystemParamValidationError {
             ShortName(&self.param),
             self.field,
             self.message
-        )
+        )?;
+        if !self.skipped {
+            write!(fmt, "\nIf this is an expected state, wrap the parameter in `Option<T>` and handle `None` when it happens, or wrap the parameter in `When<T>` to skip the system when it happens.")?;
+        }
+        Ok(())
     }
 }
 
diff --git a/crates/bevy_ecs/src/system/system_registry.rs b/crates/bevy_ecs/src/system/system_registry.rs
index cf53b35be5..272cc85d0d 100644
--- a/crates/bevy_ecs/src/system/system_registry.rs
+++ b/crates/bevy_ecs/src/system/system_registry.rs
@@ -880,7 +880,7 @@ mod tests {
             result,
             Err(RegisteredSystemError::InvalidParams { .. })
         ));
-        let expected = format!("System {id:?} did not run due to failed parameter validation: Parameter `Res<T>` failed validation: Resource does not exist");
+        let expected = format!("System {id:?} did not run due to failed parameter validation: Parameter `Res<T>` failed validation: Resource does not exist\nIf this is an expected state, wrap the parameter in `Option<T>` and handle `None` when it happens, or wrap the parameter in `When<T>` to skip the system when it happens.");
         assert_eq!(expected, result.unwrap_err().to_string());
     }