Database Proxy Error Code Descriptions

Download

Focus Mode

Font Size

Last updated: 2026-10-09 11:40:36

AI-Translated

When TencentDB for MySQL is accessed through a database proxy address, some requests are processed at the proxy layer for authentication, routing, connection management, or read/write splitting. If processing fails, the proxy returns the corresponding error code and message text to the client. Some errors are generated by the backend MySQL and forwarded by the proxy as-is. This document describes database proxy-related error codes to help you identify, alarm, and handle errors on the business side.
Note:
Error code 1999 is the unified error code for internal Proxy errors (PROXY_ERROR_CODE). To determine the specific cause, refer to the returned message text.
If your business has not previously identified error code 1999, you will receive this error in scenarios such as read-only instance removal or routing failures. We recommend that you handle error code 1999 separately or retry the request to prevent it from being treated as an unknown exception, which could cause business disruption.
Except for the Proxy-specific error codes listed in the following table, any other error code is generally an ERR packet returned by the backend MySQL and forwarded by the Proxy as-is (for example, standard MySQL errors such as 1044/1062/1205/1213), rather than being generated by the database Proxy.
Error Code Overview
Error Code
SQL State
Layer
Description
1999
HY000
Proxy itself
Unified error code for internal database proxy errors (PROXY_ERROR_CODE). See the message text for details.
1040
HY000
Proxy itself
The number of connections on the database proxy side has reached the upper limit (Too many connections).
1045
28000 / 08S01
Proxy itself
Authentication failure category (incorrect account or password, SSL requirements, handshake exceptions, and so on).
1049
42000
Proxy itself
The target database specified during connection establishment does not exist (Unknown database '%s').
Other error codes
-
Backend pass-through
ERR packets returned by the backend MySQL are forwarded by the proxy as-is (such as standard MySQL errors like 1044/1062/1205/1213), and are not generated by the database proxy.
Error Code 1999 (Proxy Internal Error) Message Details
All the following messages are returned to the client in the format of ERROR 1999 (HY000): ....
Message Text
Trigger Scenario
Proxy cannot find valid backend server.
Routing failure, no available backend found (most common: primary database or target RO unavailable/not ready), Hint routing failure, retry storage query failure.
Proxy cannot find valid backend server, reroute to ro failed.
Rerouting to the read-only backend failed in multi-primary/HTAP scenarios.
Proxy cannot find valid backend server, reroute failed.
Query rerouting failed in multi-primary scenarios.
Proxy cannot find valid backend server for query rerouting. Both AP and TP backends may be unavailable.
Both AP and TP backends are unavailable.
Backend server returned unexpected response, please check backend status.
The backend returned an unexpected response.
Backend connection not found.
Backend connection lost under race conditions.
Write backend failed, please check backend db condition.
Failed to write to the backend during transaction migration.
Proxy can't write backend connection.
Inconsistent backend connection status caused a write buffer failure.
Proxy cannot keep connection.
Session switch buffering is abnormal, and connection persistence failed.
Proxy cannot recover transaction.
Failed to replay and write transactions for momentary disconnection prevention.
Proxy internal error, please contact administrator for detail.
Failed to register the client connection with epoll (internal database proxy exception).
Can't find target instance.
The database proxy command specified an unknown instance target.
Alter database failed, can't find target instance.
The target instance was not found when databases were switched.
Alter database failed, need one database name.
The database switching command is missing the database name.
Invalid insert target.
The insertstream filter target is invalid.

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Error Code	SQL State	Layer	Description
1999	HY000	Proxy itself	Unified error code for internal database proxy errors `(PROXY_ERROR_CODE)`. See the message text for details.
1040	HY000	Proxy itself	The number of connections on the database proxy side has reached the upper limit `(Too many connections)`.
1045	28000 / 08S01	Proxy itself	Authentication failure category (incorrect account or password, SSL requirements, handshake exceptions, and so on).
1049	42000	Proxy itself	The target database specified during connection establishment does not exist `(Unknown database '%s')`.
Other error codes	-	Backend pass-through	ERR packets returned by the backend MySQL are forwarded by the proxy as-is (such as standard MySQL errors like 1044/1062/1205/1213), and are not generated by the database proxy.

Message Text	Trigger Scenario
Proxy cannot find valid backend server.	Routing failure, no available backend found (most common: primary database or target RO unavailable/not ready), Hint routing failure, retry storage query failure.
Proxy cannot find valid backend server, reroute to ro failed.	Rerouting to the read-only backend failed in multi-primary/HTAP scenarios.
Proxy cannot find valid backend server, reroute failed.	Query rerouting failed in multi-primary scenarios.
Proxy cannot find valid backend server for query rerouting. Both AP and TP backends may be unavailable.	Both AP and TP backends are unavailable.
Backend server returned unexpected response, please check backend status.	The backend returned an unexpected response.
Backend connection not found.	Backend connection lost under race conditions.
Write backend failed, please check backend db condition.	Failed to write to the backend during transaction migration.
Proxy can't write backend connection.	Inconsistent backend connection status caused a write buffer failure.
Proxy cannot keep connection.	Session switch buffering is abnormal, and connection persistence failed.
Proxy cannot recover transaction.	Failed to replay and write transactions for momentary disconnection prevention.
Proxy internal error, please contact administrator for detail.	Failed to register the client connection with epoll (internal database proxy exception).
Can't find target instance.	The database proxy command specified an unknown instance target.
Alter database failed, can't find target instance.	The target instance was not found when databases were switched.
Alter database failed, need one database name.	The database switching command is missing the database name.
Invalid insert target.	The insertstream filter target is invalid.

tencent cloud

TencentDB for MySQL

Database Proxy Error Code Descriptions

Error Code Overview

Error Code 1999 (Proxy Internal Error) Message Details

Help and Support