From 2568ccb645ecc830fc8ba8e6f752a4e729b0d909 Mon Sep 17 00:00:00 2001
From: Sadman Chowdhury Fahim <57841708+SadManFahIm@users.noreply.github.com>
Date: Mon, 16 Mar 2026 15:10:51 +0600
Subject: [PATCH] docs: clarify that None cannot be passed as a query parameter
 value
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes #12419

Added a warning note in the "Required, can be None" section to clarify
that query parameters are always strings in URLs — there is no way to
send a true Python None value via a query param.
---
 .../tutorial/query-params-str-validations.md     | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md
index 4765b36cbe..cc4a0414ff 100644
--- a/docs/en/docs/tutorial/query-params-str-validations.md
+++ b/docs/en/docs/tutorial/query-params-str-validations.md
@@ -228,6 +228,20 @@ To do that, you can declare that `None` is a valid type but simply do not declar
 
 {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
 
+/// warning
+
+Note that `None` here refers to Python's `None` value in your code logic, **not** a literal `"None"` string sent via the URL.
+
+Query parameters are always received as strings from the URL. There is no way to send a true `None` value through a query parameter — if the client omits the parameter entirely, FastAPI will return a validation error because the parameter is required.
+
+If you want a truly **optional** parameter that defaults to `None` when not sent, use a default value instead:
+
+```Python
+q: Annotated[str | None, Query(min_length=3)] = None
+```
+
+///
+
 ## Query parameter list / multiple values { #query-parameter-list-multiple-values }
 
 When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values.
@@ -331,7 +345,7 @@ Imagine that you want the parameter to be `item-query`.
 Like in:
 
 ```
-http://127.0.0.1:8000/items/?item-query=foobaritems
+http://127.0.0.18000/items/?item-query=foobaritems
 ```
 
 But `item-query` is not a valid Python variable name.