diff --git a/codex-rs/config/src/loader/mod.rs b/codex-rs/config/src/loader/mod.rs
index 49df306ab..528dedaba 100644
--- a/codex-rs/config/src/loader/mod.rs
+++ b/codex-rs/config/src/loader/mod.rs
@@ -235,7 +235,7 @@ pub async fn load_config_layers_state(
         return Err(io::Error::new(
             io::ErrorKind::InvalidData,
             format!(
-                "--profile-v2 `{active_user_profile}` cannot be used while {} contains legacy `[profiles.{active_user_profile}]` config; move those settings into {} or remove `[profiles.{active_user_profile}]`",
+                "--profile `{active_user_profile}` cannot be used while {} contains legacy `[profiles.{active_user_profile}]` config; move those settings into {} or remove `[profiles.{active_user_profile}]`. See https://developers.openai.com/codex/config-advanced#profiles for more information.",
                 base_user_file.as_path().display(),
                 active_user_file.as_path().display()
             ),
diff --git a/codex-rs/config/src/loader/tests.rs b/codex-rs/config/src/loader/tests.rs
index 2d9462bfa..812a86e25 100644
--- a/codex-rs/config/src/loader/tests.rs
+++ b/codex-rs/config/src/loader/tests.rs
@@ -120,7 +120,7 @@ model = "gpt-work"
     );
     let message = err.to_string();
     assert!(
-        message.contains("--profile-v2 `work` cannot be used"),
+        message.contains("--profile `work` cannot be used"),
         "unexpected error message: {message}"
     );
     assert!(
@@ -131,6 +131,10 @@ model = "gpt-work"
         message.contains("[profiles.work]"),
         "unexpected error message: {message}"
     );
+    assert!(
+        message.contains("https://developers.openai.com/codex/config-advanced#profiles"),
+        "unexpected error message: {message}"
+    );
 }
 
 #[tokio::test]