diff --git a/include/MySQL_Resolution.h b/include/MySQL_Resolution.h
index fe1f5568c..aad74faea 100644
--- a/include/MySQL_Resolution.h
+++ b/include/MySQL_Resolution.h
@@ -4,6 +4,14 @@
 #include <strings.h>
 #include <sys/socket.h>
 
+/**
+ * Validation, normalization, and conversion helpers for mysql-resolution_family.
+ *
+ * Supported values: "system" (AF_UNSPEC), "ipv4" (AF_INET), "ipv6" (AF_INET6).
+ * NULL or invalid values fall back to "system" / AF_UNSPEC to preserve default
+ * OS resolver behavior and avoid breaking changes.
+ */
+
 inline bool mysql_resolution_family_is_valid(const char* value) {
 	return value &&
 		(strcasecmp(value, "system") == 0 ||
@@ -12,6 +20,7 @@ inline bool mysql_resolution_family_is_valid(const char* value) {
 }
 
 inline const char* mysql_resolution_family_normalize(const char* value) {
+	// NULL or invalid values fall back to "system"
 	if (value && strcasecmp(value, "ipv4") == 0) {
 		return "ipv4";
 	}
@@ -22,6 +31,7 @@ inline const char* mysql_resolution_family_normalize(const char* value) {
 }
 
 inline int mysql_resolution_family_to_ai_family(const char* value) {
+	// NULL or invalid values fall back to AF_UNSPEC (system default)
 	if (value && strcasecmp(value, "ipv4") == 0) {
 		return AF_INET;
 	}
diff --git a/lib/MySQL_Thread.cpp b/lib/MySQL_Thread.cpp
index ecf55a9c0..a85106281 100644
--- a/lib/MySQL_Thread.cpp
+++ b/lib/MySQL_Thread.cpp
@@ -4801,6 +4801,7 @@ MySQL_Thread::MySQL_Thread() {
 	mysql_thread___add_ldap_user_comment=NULL;
 	mysql_thread___eventslog_filename=NULL;
 	mysql_thread___auditlog_filename=NULL;
+	mysql_thread___resolution_family=strdup("system");  // default: system (AF_UNSPEC)
 
 	// SSL proxy to server
 	mysql_thread___ssl_p2s_ca=NULL;
diff --git a/test/tap/tests/unit/mysql_resolution_unit-t.cpp b/test/tap/tests/unit/mysql_resolution_unit-t.cpp
index d883372c5..f26c391aa 100644
--- a/test/tap/tests/unit/mysql_resolution_unit-t.cpp
+++ b/test/tap/tests/unit/mysql_resolution_unit-t.cpp
@@ -4,6 +4,13 @@
 
 #include "MySQL_Resolution.h"
 
+// NOTE: This unit test covers the helper functions for mysql-resolution_family.
+// The actual DNS resolution path in MySQL_Monitor.cpp uses these helpers, but
+// only when the DNS cache is enabled. On DNS cache miss, the hostname is passed
+// directly to mysql_real_connect() which uses hardcoded AF_UNSPEC via the
+// MariaDB client library. This limitation is documented in the PR description.
+// A future enhancement may address this by patching the client library.
+
 int main() {
 	plan(12);