diff --git a/.env.example b/.env.example
index d258a41..4422a7b 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,5 @@
+# Values containing #, ", \ or surrounding spaces must be single-quoted
+# (dotenv 16 treats an unquoted # as a comment): DB_PASSWORD='abc#def'
 PORT=3000
 
 DB_HOST=
diff --git a/CLAUDE.md b/CLAUDE.md
index 26300fb..d2198f5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,6 +47,11 @@ Express.js REST API in TypeScript with a service-oriented layering. Domains: `Ca
 
 ## Environment
 
+dotenv 16 parses `.env` stricter than the old dotenv 8: an unquoted `#` starts a comment and
+backslash escapes inside double quotes are expanded. Wrap any value containing `#`, `"`, `\` or
+surrounding spaces in single quotes (`DB_PASSWORD='abc#def'`), which are taken literally.
+A truncated password shows up as MariaDB "Access denied ... (using password: YES)".
+
 Copy `.env.example` (or create `.env`) with:
 ```
 PORT=