diff --git a/versioned_docs/version-4.0.0/keploy-explained/common-errors.md b/versioned_docs/version-4.0.0/keploy-explained/common-errors.md
index cd18c332bc..18adb288ef 100644
--- a/versioned_docs/version-4.0.0/keploy-explained/common-errors.md
+++ b/versioned_docs/version-4.0.0/keploy-explained/common-errors.md
@@ -194,6 +194,36 @@ Keploy does not support the protocol or API structure you are using (e.g., gRPC,
 - Confirm the supported protocols (currently HTTP/REST and GraphQL).
 - Consider alternative tools or frameworks for unsupported protocols.
 
+### 12. MySQL connection hangs during the handshake
+
+#### Description:
+
+Your application cannot reach MySQL while Keploy is running. The client reports a lost connection during the handshake, and the application often never finishes starting because its connection pool is stuck:
+
+```
+ERROR 2013 (HY000): Lost connection to server at 'handshake: reading initial communication packet'
+```
+
+The same setup connects normally when you run it without Keploy.
+
+#### Possible Cause:
+
+- `disableMysqlAutoDetect` is set to `true`, and the port your database listens on is not listed in `mysqlPorts`.
+- You are running a Keploy version that predates automatic MySQL port detection, which recognised only `3306` and `4000` unless you configured `mysqlPorts`.
+
+#### Solution:
+
+- Remove `disableMysqlAutoDetect` from your config file, or set it to `false`. Keploy then identifies MySQL on any port on its own.
+- If you need detection off, list every MySQL port your application uses:
+
+  ```yaml
+  mysqlPorts: [3307, 6033]
+  ```
+
+- On an older Keploy version, upgrade, or add the port to `mysqlPorts`.
+
+See [MySQL port detection](../running-keploy/configuration-file.md#mysql-port-detection) for how Keploy identifies the protocol during Record and recovers the port during Test.
+
 If you’re still encountering issues after trying these solutions, feel free to reach out to the Keploy team on [Slack](https://keploy.io/slack).
 
 Happy Testing!
diff --git a/versioned_docs/version-4.0.0/running-keploy/configuration-file.md b/versioned_docs/version-4.0.0/running-keploy/configuration-file.md
index 4974588571..2e209b702d 100644
--- a/versioned_docs/version-4.0.0/running-keploy/configuration-file.md
+++ b/versioned_docs/version-4.0.0/running-keploy/configuration-file.md
@@ -74,6 +74,8 @@ record:
   filters: []
 configPath: ""
 bypassRules: []
+mysqlPorts: []
+disableMysqlAutoDetect: false
 cmdType: "native"
 enableTesting: false
 keployContainer: "keploy-v3"
@@ -164,6 +166,40 @@ The `record` section in the Keploy-config file allows you to define parameters f
         port: 0
   ```
 
+- **`mysqlPorts`**: Extra ports to treat as MySQL. You rarely need this — Keploy detects MySQL automatically on any port. See [MySQL port detection](#mysql-port-detection).
+
+- **`disableMysqlAutoDetect`**: Turns off automatic MySQL port detection. Default is `false`.
+
+### MySQL port detection
+
+Keploy identifies MySQL on any port, so you do not have to tell it where your database listens. This matters when MySQL, or a MySQL wire-compatible service, runs somewhere other than the usual `3306` — a second instance on `3307`, ProxySQL on `6033`, MaxScale on `4006`, StarRocks on `9030`, or a Cloud SQL Auth Proxy on whatever port you gave it.
+
+Detection works differently in each mode, because each mode has different information available:
+
+- **During Record**, Keploy reads the first bytes the database server sends. MySQL greets a new connection with a handshake packet, so Keploy identifies the protocol from that greeting and routes the connection to its MySQL parser.
+
+- **During Test**, no database is running — Keploy serves the Mocks it recorded. It recovers the port from those Mocks, which store the address each connection was recorded against.
+
+Together this means a port you recorded on is replayed correctly with no configuration.
+
+#### When to set these fields
+
+Both fields are optional and most projects leave them alone.
+
+Set `mysqlPorts` to skip detection for a port you already know about. Keploy always treats `3306` and `4000` as MySQL; listing a port here adds it to that set. The only practical benefit is avoiding a short probe on the first connection to that port.
+
+```yaml
+mysqlPorts: [3307, 6033]
+```
+
+Set `disableMysqlAutoDetect` to `true` to turn detection off entirely and match `mysqlPorts` strictly:
+
+```yaml
+disableMysqlAutoDetect: true
+```
+
+With detection disabled, a MySQL server on a port outside `mysqlPorts` cannot complete its handshake, and your application fails to connect. Only disable detection if you also list every MySQL port your application uses.
+
 ### Test Section
 
 The `test` section in the Keploy-config file allows you to define parameters for testing API calls.