diff --git a/docs/en/appendices/6-0-migration-guide.md b/docs/en/appendices/6-0-migration-guide.md
index 6832c801e6..01d54b2fcb 100644
--- a/docs/en/appendices/6-0-migration-guide.md
+++ b/docs/en/appendices/6-0-migration-guide.md
@@ -131,6 +131,13 @@ Some properties have also been renamed to better reflect their purpose. These ar
 - The methods `_getCookies()`, `_getJson()`, `_getXml()`, `_getHeaders()`
   and `_getBody()` have been removed. Use/Overwrite their non-prefixed public alternative instead.
 
+- URL parsing now uses PHP 8.5's `Uri\WhatWg\Url` and `Uri\Rfc3986\Uri`
+  parsers. Review malformed or relative URL inputs and exception handling. In
+  particular, `Client::createFromUrl()` can now throw
+  `Uri\WhatWg\InvalidUrlException` for inputs previously rejected with
+  `InvalidArgumentException`. See
+  [Creating Scoped Clients](../core-libraries/httpclient#http_client_scoped_client).
+
 ### ORM
 
 - The `_accessible` property inside Entities has been renamed to `patchable`
diff --git a/docs/en/core-libraries/httpclient.md b/docs/en/core-libraries/httpclient.md
index 3c4c13083f..aa5f2a4948 100644
--- a/docs/en/core-libraries/httpclient.md
+++ b/docs/en/core-libraries/httpclient.md
@@ -308,8 +308,15 @@ If your scoped client only needs information from the URL you can use
 $http = Client::createFromUrl('https://api.example.com/v1/test');
 ```
 
-The above would create a client instance with the `protocol`, `host`, and
-`basePath` options set.
+The above creates a client with `scheme`, `host`, `port` and `basePath`
+options derived from the URL. Query strings and fragments are not used to
+configure the scoped client.
+
+`createFromUrl()` uses PHP's WHATWG URL parser. Supply an absolute URL with
+a scheme and host. Malformed or relative URLs can throw
+`Uri\WhatWg\InvalidUrlException`; a parsed URL with no host raises
+`InvalidArgumentException`. The parser normalizes URLs, including removing
+default ports such as `:80` from HTTP URLs.
 
 The following information can be used when creating a scoped client: