diff --git a/sdk/program/src/instruction.rs b/sdk/program/src/instruction.rs
index a158d1883f..64e493129f 100644
--- a/sdk/program/src/instruction.rs
+++ b/sdk/program/src/instruction.rs
@@ -9,6 +9,14 @@ use serde::Serialize;
 use thiserror::Error;
 
 /// Reasons the runtime might have rejected an instruction.
+///
+/// Instructions errors are included in the bank hashes and therefore are
+/// included as part of the transaction results when determining consensus.
+/// Because of this, members of this enum must not be removed, but new ones can
+/// be added.  Also, it is crucial that meta-information if any that comes along
+/// with an error be consistent across software versions.  For example, it is
+/// dangerous to include error strings from 3rd party crates because they could
+/// change at any time and changes to them are difficult to detect.
 #[derive(
     Serialize, Deserialize, Debug, Error, PartialEq, Eq, Clone, AbiExample, AbiEnumVisitor,
 )]
@@ -197,6 +205,14 @@ pub enum InstructionError {
     IncorrectAuthority,
 
     /// Failed to serialize or deserialize account data
+    ///
+    /// Warning: This error should never be emitted by the runtime.
+    ///
+    /// This error includes strings from the underlying 3rd party Borsh crate
+    /// which can be dangerous beause the error strings could change across
+    /// Borsh versions. Only programs can use this error because they are
+    /// consistent across Solana software versions.
+    ///
     #[error("Failed to serialize or deserialize account data: {0}")]
     BorshIoError(String),