From 18d4557047326cf38523e24e1883ff42d869744a Mon Sep 17 00:00:00 2001 From: slayerjain Date: Wed, 29 Jul 2026 05:45:17 +0530 Subject: [PATCH] docs: document automatic MySQL port detection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keploy now identifies MySQL on any port rather than only 3306/4000 plus whatever mysqlPorts listed (keploy/keploy#4389). Nothing described that, and mysqlPorts itself was never documented at all — a user whose MySQL ran on 3307, behind ProxySQL, or on a Cloud SQL Auth Proxy hit a stuck handshake with no discoverable fix. Adds a "MySQL port detection" section to the configuration reference covering how detection works in each mode (reading the server handshake during Record, recovering the port from Mocks during Test), documents mysqlPorts and the new disableMysqlAutoDetect field, and explains when either is worth setting. Adds a troubleshooting entry for the symptom users actually search for — "Lost connection to server at 'handshake: reading initial communication packet'" — since that error is what surfaces when detection is disabled or the Keploy version predates it. Signed-off-by: slayerjain --- .../keploy-explained/common-errors.md | 30 ++++++++++++++++ .../running-keploy/configuration-file.md | 36 +++++++++++++++++++ 2 files changed, 66 insertions(+) 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.