diff --git a/README.md b/README.md
index bf66fe2e7..6ba6f9ba5 100644
--- a/README.md
+++ b/README.md
@@ -396,6 +396,11 @@ Response response = client
 
 Supported schemes: **Basic**, **Digest**, **NTLM**, **SPNEGO/Kerberos**, **SCRAM-SHA-256**.
 
+SPNEGO/Kerberos canonical-hostname resolution is disabled by default. Enabling it with
+`setUseCanonicalHostname(true)` performs a blocking JVM lookup while generating the authentication token; during
+an authentication retry, that work can run on a Netty event-loop thread. When the service principal name is known,
+provide it with `setServicePrincipalName(...)` instead of enabling hostname canonicalization.
+
 ## Proxy Support
 
 ```java
diff --git a/client/src/main/java/org/asynchttpclient/Realm.java b/client/src/main/java/org/asynchttpclient/Realm.java
index cf770dafe..46e1d7aeb 100644
--- a/client/src/main/java/org/asynchttpclient/Realm.java
+++ b/client/src/main/java/org/asynchttpclient/Realm.java
@@ -221,6 +221,9 @@ public boolean isOmitQuery() {
         return servicePrincipalName;
     }
 
+    /**
+     * Returns whether SPNEGO/Kerberos authentication canonicalizes the target hostname through the JVM resolver.
+     */
     public boolean isUseCanonicalHostname() {
         return useCanonicalHostname;
     }
@@ -421,6 +424,11 @@ public Builder setServicePrincipalName(@Nullable String servicePrincipalName) {
             return this;
         }
 
+        /**
+         * Enables JVM canonical-hostname resolution when deriving the SPNEGO/Kerberos service principal name.
+         * Resolution is blocking and can run on a Netty event-loop thread during authentication retries. Prefer
+         * {@link #setServicePrincipalName(String)} when the service principal name is known.
+         */
         public Builder setUseCanonicalHostname(boolean useCanonicalHostname) {
             this.useCanonicalHostname = useCanonicalHostname;
             return this;