docs: say that 3306 and 4000 are only a hint for MySQL

versioned_docs/version-4.0.0/keploy-explained/common-errors.md

@@ -293,6 +293,26 @@ or Podman can't find the application's image although `podman images` (without `
 - For compose, install Docker Compose (`docker-compose`) on that `PATH` and keep `podman-compose` out of containers.conf's `compose_providers`, or set `PODMAN_COMPOSE_PROVIDER` to docker-compose's path; and run it on a host with systemd, or use `podman run`.
 - Build or pull the image with `sudo podman`. See [Platform requirements](/docs/concepts/platform-requirements/#podman).
 
+### 15. An HTTP service on port 3306 or 4000 gets no answer while recording
+
+#### Description:
+
+Your application calls an HTTP service on port `4000` (a common development port) or `3306`. Under `keploy record` the call never gets a response, and the client waits until its own timeout. The same service on another port works, and so does the call without Keploy.
+
+#### Possible Cause:
+
+- The port is listed in `mysqlPorts`. Keploy pins a listed port to MySQL and waits for a MySQL greeting that an HTTP service never sends.
+- `disableMysqlAutoDetect` is set to `true` and `mysqlPorts` is empty, which pins `3306` and `4000` to MySQL.
+- You are running an older Keploy version that took every connection to `3306` or `4000` for MySQL.
+
+#### Solution:
+
+- Remove the port from `mysqlPorts`. List only ports that serve MySQL.
+- Remove `disableMysqlAutoDetect` from your config file, or set it to `false`.
+- On an older Keploy version, upgrade.
+
+See [MySQL port detection](../running-keploy/configuration-file.md#mysql-port-detection) for how Keploy tells MySQL from other protocols on these ports.
+
 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!

versioned_docs/version-4.0.0/running-keploy/configuration-file.md

@@ -166,7 +166,7 @@ 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).
+- **`mysqlPorts`**: Ports to pin to MySQL. You rarely need this — Keploy detects MySQL automatically on any port. A list replaces the built-in `3306` and `4000`, and an HTTP service on a listed port gets no answer. See [MySQL port detection](#mysql-port-detection).
 
 - **`disableMysqlAutoDetect`**: Turns off automatic MySQL port detection. Default is `false`.
 
@@ -176,17 +176,19 @@ Keploy identifies MySQL on any port, so you do not have to tell it where your da
 
 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 Record**, whichever side of the connection speaks first decides. MySQL greets a new connection with a handshake packet before the client sends anything, so when the server speaks first, Keploy identifies the protocol from that greeting and routes the connection to its MySQL parser. When the client speaks first, as an HTTP, gRPC, or PostgreSQL client does, the connection isn't MySQL, and Keploy routes it by the client's bytes.
 
-- **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.
+- **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. On `3306` and `4000` the recording decides too: if Keploy recorded an HTTP or gRPC service on that port and no MySQL there, it replays the port as that protocol.
 
-Together this means a port you recorded on is replayed correctly with no configuration.
+Together this means a port you recorded on is replayed correctly with no configuration. Keploy treats `3306` and `4000` as a hint, not a rule, so an HTTP service on either port, such as a development server on `4000`, records and replays as HTTP.
 
 #### 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.
+Set `mysqlPorts` to pin a port to MySQL and skip detection for it. Keploy then waits for a MySQL greeting on every connection to a listed port, so an HTTP service on a port you list gets no answer. List only ports that serve MySQL.
+
+A list replaces the built-in `3306` and `4000`. While detection is on, Keploy still identifies MySQL on those ports the same way it does on any other port.
 
 ```yaml
 mysqlPorts: [3307, 6033]
@@ -198,7 +200,7 @@ Set `disableMysqlAutoDetect` to `true` to turn detection off entirely and match
 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.
+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. With detection disabled and `mysqlPorts` empty, Keploy pins `3306` and `4000` to MySQL, so an HTTP service on either port gets no answer.
 
 ### Test Section