diff --git a/src/env_var.zig b/src/env_var.zig
index 49d034f755..cdd75eda12 100644
--- a/src/env_var.zig
+++ b/src/env_var.zig
@@ -8,6 +8,12 @@
 //! If default values are provided, the .get() method is guaranteed not to return a nullable type,
 //! whereas if no default is provided, the .get() method will return an optional type.
 //!
+//! Note that environment variables may fail to parse silently. If they do fail to parse, the
+//! default is to show a debug warning and treat them as not set. This behavior can be customized,
+//! but environment variables are not meant to be a robust configuration mechanism. If you do think
+//! your feature needs more customization, consider using other means. The reason we have decided
+//! upon this behavior is to avoid panics due to environment variable pollution.
+//!
 //! TODO(markovejnovic): It would be neat if this library supported loading floats as
 //!                      well as strings, integers and booleans, but for now this will do.
 //!
@@ -341,6 +347,9 @@ const kind = struct {
             default: ?ValueType = null,
             deser: struct {
                 /// Control how deserializing and deserialization errors are handled.
+                ///
+                /// Note that deserialization errors cannot panic. If you need more robust means of
+                /// handling inputs, consider not using environment variables.
                 error_handling: enum {
                     /// debug_warn on deserialization errors.
                     debug_warn,