Common PolarDB-X error codes and solutions-PolarDB(PolarDB)-阿里云帮助中心

TDDL-1305 ERR_UNKNOWN_SAVEPOINT

Description: The specified savepoint does not exist.
Example: ERR-CODE: [TDDL-1305][ERR_UNKNOWN_SAVEPOINT] SAVEPOINT ***** does not exist
In PolarDB-X, this error occurs when you execute the ROLLBACK TO SAVEPOINT or RELEASE SAVEPOINT statement for a savepoint that does not exist.

Make sure that the savepoint name you use matches the one returned by the savepoint statement.

TDDL-1094 ERR_UNKNOWN_THREAD_ID

Description: The session ID specified in the KILL command does not exist.
Example: ERR-CODE: [TDDL-1094][ERR_UNKNOWN_THREAD_ID] Unknown thread id: *****
Explanation: This error occurs when you execute the KILL command on PolarDB-X to terminate an SQL statement, but the specified session ID does not exist or the SQL statement has already finished.

Run SHOW PROCESSLIST to get the session ID of the running SQL statement, and use KILL only on an ID returned by that command.

TDDL-4006 ERR_TABLE_NOT_EXIST

Description: The PolarDB-X data table does not exist.
Example: ERR-CODE: [TDDL-4006][ERR_TABLE_NOT_EXIST] Table '*****' doesn't exist.
Note: This error code indicates that the PolarDB-X data table does not exist, or for unknown reasons, PolarDB-X cannot load the metadata for the data table.

TDDL-4007 ERR_CANNOT_FETCH_TABLE_META

Description: This error occurs when PolarDB-X fails to load table metadata.
Example: ERR-CODE: [TDDL-4007][ERR_CANNOT_FETCH_TABLE_META] Table '*****' metadata cannot be fetched because Table '*****.*****' doesn't exist.
Explanation: This error occurs when PolarDB-X fails to read table metadata. Possible causes include:
- The table has not been created.
- The metadata in the metadatabase is inconsistent.
- The table was deleted or renamed.
If this error occurs, first check that the table exists. Alternatively, run the CHECK TABLE command to verify the consistency of PolarDB-X's metadatabase. If the table was manually deleted or renamed, use PolarDB-X's data recovery feature. If the issue persists, contact technical support.

TDDL-4018 ERR_INVALID_DDL_PARAMS

Description: PolarDB-X failed to execute a DDL operation.
Example: ERR-CODE: [TDDL-4018][ERR_INVALID_DDL_PARAMS] invalid '*****'.
Explanation: This error occurs when a DDL statement contains an invalid parameter. Verify that all parameters are correct. If the error persists, contact technical support.

TDDL-4100 ERR_ATOM_NOT_AVALILABLE

Description: A backend data node of PolarDB-X is temporarily unavailable.
Example: ERR-CODE: [TDDL-4100][ERR_ATOM_NOT_AVALILABLE] Atom : ***** isNotAvailable
Note: If PolarDB-X detects an abnormal backend data node, it temporarily blocks access to the instance and returns this error.

If you encounter this error, check the status of all backend data nodes of PolarDB-X. When a data node recovers, PolarDB-X automatically restores its availability and allows applications to resume normal access.

TDDL-4101 ERR_ATOM_GET_CONNECTION_FAILED_UNKNOWN_REASON

Description: A PolarDB-X compute node cannot connect to a data node.
Example: ERR-CODE: [TDDL-4101][ERR_ATOM_GET_CONNECTION_FAILED_UNKNOWN_REASON] Get connection for db '*****' from pool failed. AppName:*****, Env:*****, UnitName:null. Message from pool: wait millis 5000, active 0, maxActive 5. You should look for the following logs which contains the real reason.
Note: When PolarDB-X processes a request, it asynchronously creates a connection to a data node. If a connection is not established within the timeout period and the asynchronous task returns no specific error, PolarDB-X returns the TDDL-4101 error to the application.

An exception on a backend data node typically causes this error. If the error persists after you troubleshoot the data nodes, contact technical support.

TDDL-4102 ERR_ATOM_GET_CONNECTION_FAILED_KNOWN_REASON

Description: Failure to get a backend connection in PolarDB-X due to a known reason.
Example: ERR-CODE: [TDDL-4102][ERR_ATOM_GET_CONNECTION_FAILED_KNOWN_REASON] Get connection for db '*****' failed because wait millis 5000, active 0, maxActive 5
Note: A PolarDB-X compute node failed to obtain a connection to a data node. The reason for the failure is provided in the ERR-CODE message. Common reasons for connection failures to a PolarDB-X data node are as follows:
- The backend data node has reached its maximum number of connections.
- The connection from the compute node to the data node timed out.
- The data node refused the connection.
If the error persists after ruling out issues with the backend data node, contact technical support.

TDDL-4103 ERR_ATOM_CONNECTION_POOL_FULL

Description: The connection pool for a PolarDB-X backend data node is full.
Example: ERR-CODE: [TDDL-4103][ERR_ATOM_CONNECTION_POOL_FULL] Pool of DB '*****' is full. Message from pool: wait millis 5000, active 5, maxActive 5. AppName:*****, Env:*****, UnitName:null.
Explanation: This error occurs when the backend connection pool for PolarDB-X is full. Common causes for this error include:
- Slow-running SQL statements from an application hold connections for extended periods, causing a shortage of available connections.
- A connection leak occurs when the application does not properly close database connections.
- Many concurrent cross-database queries, such as aggregation queries or queries without a sharding key condition, consume many connections.
To resolve this issue, try the following solutions:
- Use a framework, such as Spring JDBC or MyBatis, to access the database.
- Optimize SQL statements based on performance analysis reports and recommendations from a database administrator.
- Use the PolarDB-X read/write splitting feature to forward cross-database queries to read-only nodes.
- Upgrade your PolarDB-X instance to a higher specification to improve backend processing capacity.
- Contact technical support to adjust the number of connections on the PolarDB-X backend.

TDDL-4104 ERR_ATOM_CREATE_CONNECTION_TOO_SLOW

Description: Creating a connection to a PolarDB-X data node is too slow.
Example: ERR-CODE: [TDDL-4104][ERR_ATOM_CREATE_CONNECTION_TOO_SLOW] Get connection for db '*****' from pool timeout. AppName:*****, Env:*****, UnitName:null. Message from pool: wait millis 5000, active 3, maxActive 5.
Explanation: PolarDB-X creates connections to its data nodes asynchronously. This process can time out if too many connections are requested too quickly or if a data node is slow to accept them. This issue is typically caused by excessive load or exceptions on the data nodes. To reduce the backend load, use the read/write splitting feature of PolarDB-X or upgrade your instance to a higher specification.

If the error persists after ruling out data node issues, contact technical support. If the issue is caused by creating too many connections too quickly, contact technical support to adjust the minimum number of connections for PolarDB-X.

TDDL-4105 ERR_ATOM_ACCESS_DENIED

Description: A backend data node of PolarDB-X denied a connection request.
Example: ERR-CODE: [TDDL-4105][ERR_ATOM_ACCESS_DENIED] DB '*****' Access denied for user '*****'@'*****'. AppName:*****, Env:*****, UnitName:null. Please contact DBA to check.
Explanation: This error indicates that PolarDB-X failed to connect to a data node because the specified username and password were not authorized. To resolve this issue, contact technical support.

TDDL-4106 ERR_ATOM_DB_DOWN

Description: This error indicates that PolarDB-X cannot connect to a backend data node.
Example: ERR-CODE: [TDDL-4106][ERR_ATOM_DB_DOWN] DB '*****' cannot be connected. AppName:*****, Env:*****, UnitName:null. It seems a very real possibility that this DB IS DOWN. Please contact DBA to check.
Note: This error occurs when a connection from PolarDB-X to a backend data node times out or the node fails to respond. A data node failure typically causes this issue. To resolve this issue, contact technical support.

TDDL-4108 ERR_VARIABLE_CAN_NOT_SET_TO_NULL_FOR_NOW

Description: Certain variables cannot be set to NULL.
Example: ERR-CODE: [TDDL-4108][ERR_VARIABLE_CAN_NOT_SET_TO_NULL_FOR_NOW] System variable ***** can''t set to null for now;
Explanation: You cannot set certain data node variables to NULL with the SET var = x statement. If you do, PolarDB-X returns the TDDL-4108 error.

TDDL-4200 ERR_GROUP_NOT_AVALILABLE

Description: A data node in PolarDB-X is temporarily unavailable.
Example: ERR-CODE: [TDDL-4200][ERR_GROUP_NOT_AVALILABLE] The TDDL Group ***** is running in fail-fast status, caused by this SQL:***** which threw a fatal exception as *****.
Explanation: When a data node within a database shard becomes inaccessible and no other data nodes are available in that shard, PolarDB-X places the database shard in a fail-fast state and returns the TDDL-4200 error.

A data node failure typically causes this error. Locate and resolve the issue based on the exception information for the affected data node. After the failed data node recovers, PolarDB-X automatically clears the fail-fast state.

If the TDDL-4200 error persists after you resolve the data node failure, contact technical support.

TDDL-4201 ERR_GROUP_NO_ATOM_AVALILABLE

Description: No data nodes are available in a PolarDB-X database shard.
Example: ERR-CODE: [TDDL-4201][ERR_GROUP_NO_ATOM_AVALILABLE] All weights of DBs in Group '*****' is 0. Weights is: *****.
Explanation: PolarDB-X returns the TDDL-4201 error when all data nodes in a database shard are unavailable or in the fail-fast state.

A data node failure typically causes this error. Check the status of the backend data nodes to locate and resolve the issue. If the error persists after you resolve the failure, contact technical support.

TDDL-4202 ERR_SQL_QUERY_TIMEOUT

Description: A PolarDB-X query timed out.
Example: ERR-CODE: [TDDL-4202][ERR_SQL_QUERY_TIMEOUT] Slow query leads to a timeout exception, please contact DBA to check slow sql. SocketTimout:*** ms, Atom:*****, Group:*****, AppName:*****, Env:*****, UnitName:null.
Explanation: This error occurs when the execution time of an SQL statement on a backend data node exceeds the socketTimeout limit in PolarDB-X. By default, the PolarDB-X query timeout (socketTimeout) is 900 seconds.

To resolve this issue, optimize the SQL statement and create an appropriate index on the backend data node to improve performance. If the SQL statement is still slow after optimization, you can use the following hint syntax to temporarily set the PolarDB-X query timeout: /*TDDL:SOCKET_TIMEOUT=900000*/ SELECT * FROM dual;. SOCKET_TIMEOUT is in milliseconds for PolarDB-X. How to customize the SQL timeout period. Contact technical support to permanently adjust the PolarDB-X query timeout.

TDDL-4203 ERR_SQL_QUERY_MERGE_TIMEOUT

Description: A PolarDB-X distributed query timed out.
Example: ERR-CODE: [TDDL-4203][ERR_SQL_QUERY_MERGE_TIMEOUT] Slow sql query leads to a timeout exception during merging results, please optimize the slow sql. The the default timeout is *** ms. DB is *****
Note: This error occurs when a PolarDB-X distributed query times out. By default, the timeout is 900 seconds. This error means an SQL statement that scanned multiple database shards took longer than the 900-second limit to execute.
Recommended optimizations:
- Include a shard key condition in the WHERE clause to optimize the SQL statement so that it runs on a single database shard.
- Create a suitable index on the backend data nodes to improve data scanning performance on each database shard.
- Eliminate time-consuming operations like cross-database JOINs and data reordering in distributed queries to reduce resource consumption during the PolarDB-X data merge phase.
If the query is still slow after optimization, use the following hint to temporarily increase the timeout for PolarDB-X: /*TDDL:SOCKET_TIMEOUT=900000*/ SELECT * FROM dual;. SOCKET_TIMEOUT is in milliseconds for PolarDB-X. How to customize the SQL timeout period.

TDDL-4400 ERR_SEQUENCE

Description: Failure to process a sequence (globally unique sequence).
Example: ERR-CODE: [TDDL-4400][ERR_SEQUENCE] Sequence : All dataSource faild to get value!
Explanation: This error indicates a failure to process a sequence. Error details follow the Sequence : string. A common cause for TDDL-4400 is a data node failure that prevents access to sequence-related tables.

First, check the status of the backend data nodes. If the error persists after you rule out data node failures, contact technical support.

TDDL-4401 ERR_MISS_SEQUENCE

Description: The specified sequence does not exist.
Example: ERR-CODE: [TDDL-4401][ERR_MISS_SEQUENCE] Sequence '*****' is not found
Explanation: The sequence name specified in the statement does not exist. Run the SHOW SEQUENCES statement to check the names of all created sequences in PolarDB-X and use a valid sequence name.
If the sequence does not exist, use the following statement to create it:
```
CREATE SEQUENCE <sequence name> [ START WITH <numeric value> ] 
[ INCREMENT BY <numeric value> ] [ MAXVALUE <numeric value> ] 
[ CYCLE | NOCYCLE ]` 
```
If the PolarDB-X sequence exists but the TDDL-4401 error persists, contact technical support. Overview.

TDDL-4403 ERR_MISS_SEQUENCE_TABLE_ON_DEFAULT_DB

Description: The sequence table does not exist.
Example: ERR-CODE: [TDDL-4403][ERR_MISS_SEQUENCE_TABLE_ON_DEFAULT_DB] Sequence table is not in default db.
Explanation: The tables named sequence or sequence_opt are inaccessible in the PolarDB-X backend database. To resolve this issue, contact technical support.

TDDL-4404 ERR_SEQUENCE_TABLE_META

Description: The sequence table schema is invalid.
Example: ERR-CODE: [TDDL-4404][ERR_SEQUENCE_TABLE_META] the meta of sequence table is error, some columns missed
Explanation: Required fields are missing from the sequence tables (such as sequence or sequence_opt). Contact technical support.

TDDL-4405 ERR_INIT_SEQUENCE_FROM_DB

Description: This error indicates a sequence initialization failure.
Example: ERR-CODE: [TDDL-4405][ERR_INIT_SEQUENCE_FROM_DB] init sequence manager error: *****
Explanation: This error occurs when a sequence fails to initialize. The message following 'init sequence manager error' details the specific cause. First, check the status of the PolarDB-X backend data nodes. If the TDDL-4405 error persists after resolving any data node failures, contact technical support.

TDDL-4407 ERR_OTHER_WHEN_BUILD_SEQUENCE

Description: Failed to access a sequence table.
Example: ERR-CODE: [TDDL-4407][ERR_OTHER_WHEN_BUILD_SEQUENCE] error when build sequence: *****
Explanation: This error occurs when accessing a sequence-related table, such as sequence or sequence_opt. The specific error message appears after the error when build sequence: string.

First, check the status of the PolarDB-X backend data nodes. If the TDDL-4407 error persists after you rule out data node failures, contact technical support.

TDDL-4408 ERR_SEQUENCE_NEXT_VALUE

Description: Occurs when retrieving the next value from a sequence fails.
Example: ERR-CODE: [TDDL-4408][ERR_SEQUENCE_NEXT_VALUE] error when get sequence's next value, sequence is: *****, error: *****
Explanation: This error occurs when you use an auto-increment primary key in PolarDB-X or manually retrieve a GUID by using the <sequence name>.NEXTVAL syntax. The error: prompt details the specific cause.

A backend data node failure typically causes this error. Check the status and access load of the PolarDB-X backend data nodes. If the error persists after troubleshooting the backend data nodes, contact technical support.

TDDL-4500 ERR_PARSER

Description: Failed to parse the SQL statement.
Example: ERR-CODE: [TDDL-4500][ERR_PARSER] not support statement: '*****'
Note: PolarDB-X supports SQL syntax that is compliant with the SQL-92 standard, as well as syntax extensions and functions supported by MySQL. Verify that your SQL statements conform to the standards supported by PolarDB-X and MySQL.

Check your SQL against the standard SQL syntax reference and limits on SQL syntax. If the TDDL-4500 error persists, contact technical support.

TDDL-4501 ERR_OPTIMIZER

Description: The optimizer fails to convert an SQL statement.
Example: ERR-CODE: [TDDL-4501][ERR_OPTIMIZER] optimize error by: Unknown column '*****' in 'order clause'
Explanation: This error occurs when the PolarDB-X optimizer cannot convert an SQL statement into an internal syntax tree due to a logic error in the statement.

Use the message following 'optimize error by' to correct your SQL statement. If the error persists, contact technical support.

TDDL-4502 ERR_OPTIMIZER_MISS_ORDER_FUNCTION_IN_SELECT

Description: The function column in the ORDER BY clause is missing from the SELECT clause.
Example: ERR-CODE: [TDDL-4502][ERR_OPTIMIZER_MISS_ORDER_FUNCTION_IN_SELECT] Syntax Error: orderBy/GroupBy Column ***** is not existed in select clause`
Explanation: In PolarDB-X, any function column (such as RAND()) used in an ORDER BY clause must also appear in the SELECT clause of the same SQL statement. Failing to do so triggers the TDDL-4502 error.

Add the corresponding function column to the SELECT clause.

TDDL-4504 ERR_OPTIMIZER_SELF_CROSS_JOIN

Description: A required shard key condition is missing for the SELF JOIN.
Example: ERR-CODE: [TDDL-4504][ERR_OPTIMIZER_SELF_CROSS_JOIN] self cross join case, add shard column filter on right table
Note: This error occurs during a SELF JOIN in PolarDB-X if the where clause specifies a shard key condition for only the left table or the right table.

To resolve this, ensure the SQL statement's where clause includes shard key conditions for both the left and right tables.

TDDL-4506 ERR_MODIFY_SHARD_COLUMN

Description: You cannot update the sharding key.
Example: ERR-CODE: [TDDL-4506][ERR_MODIFY_SHARD_COLUMN] Column '*****' is a sharding key of table '*****', which is forbidden to be modified.
Explanation: This error occurs when you attempt to modify a sharding key. In PolarDB-X, you cannot modify the sharding key of a table that has a global secondary index.

As a workaround, replace the UPDATE statement with an equivalent INSERT and a DELETE statement.

TDDL-4508 ERR_OPTIMIZER_NOT_ALLOWED_SORT_MERGE_JOIN

Description: Cannot perform a sort-merge join.
Example: ERR-CODE: [TDDL-4508][ERR_OPTIMIZER_NOT_ALLOWED_SORT_MERGE_JOIN] sort merge join is not allowed when missing equivalent filter
Explanation: If an SQL statement joins tables located on different data nodes, PolarDB-X prioritizes the sort-merge join algorithm. This algorithm requires an equality join condition between the left and right tables. Otherwise, PolarDB-X reports the TDDL-4508 error.

To resolve this, add an equality join condition to the JOIN or WHERE clause.

TDDL-4509 ERR_OPTIMIZER_ERROR_HINT

Example: ERR-CODE: [TDDL-4509][ERR_OPTIMIZER_ERROR_HINT] Hint Syntax Error: unexpected operation: *****.
Explanation: PolarDB-X cannot parse the hint syntax in your SQL statement. Correct the syntax per How to use hints.

TDDL-4510 ERR_CONTAINS_NO_SHARDING_KEY

Description: The shard key condition is missing.
Example: ERR-CODE: [TDDL-4510][ERR_CONTAINS_NO_SHARDING_KEY] Your SQL contains NO SHARDING KEY '*****' for table '*****', which is not allowed in DEFAULT.
Explanation: This error occurs when a query without a shard key condition attempts a full table scan on a table where full table scans are disabled. By default, PolarDB-X enables full table scans when a table is created. If you manually disable this feature, ensure that all SQL statements for that table include a shard key condition.

TDDL-4511 ERR_INSERT_CONTAINS_NO_SHARDING_KEY

Description: The INSERT statement is missing a shard key.
Example: ERR-CODE: [TDDL-4511][ERR_INSERT_CONTAINS_NO_SHARDING_KEY] Your INSERT SQL contains NO SHARDING KEY '*****' for table '*****'.
An INSERT statement for a PolarDB-X sharded table must include a shard key value. This requirement does not apply if the shard key is an auto-increment primary key. Otherwise, PolarDB-X returns the TDDL-4511 error.

To resolve this error, include the shard key value in the INSERT statement.

TDDL-4515 ERR_CONNECTION_CHARSET_NOT_MATCH

Description: The character set of an input string does not match the character set of the database.
Example: ERR-CODE: [TDDL-4515][ERR_CONNECTION_CHARSET_NOT_MATCH] Caused by MySQL's character_set_connection doesn't match your input charset. Partition DDL can only take ASCII or chinese column name. If you want use chinese table or column name, Make sure MySQL connection's charset support chinese character. Use "set names xxx" to set correct charset.
Explanation: PolarDB-X supports Chinese characters in table names and column names. This error occurs when you run an SQL statement that contains Chinese characters, but the connection character set, specified by the character_set_connection variable, is set to an incompatible value, such as latin1.

Run SHOW VARIABLES LIKE 'character_set_connection' to query the MySQL client's current connection character set. To change the connection character set, use the SET NAMES command. When connecting to PolarDB-X from a Java application using JDBC, set the characterEncoding parameter.

TDDL-4517 ERR_MODIFY_SYSTEM_TABLE

Description: You cannot modify system tables.
Example: ERR-CODE: [TDDL-4517][ERR_MODIFY_SYSTEM_TABLE] Table '*****' is PolarDB-XSYSTEM TABLE, which is forbidden to be modified.
Explanation: PolarDB-X maintains a set of internal system tables that are critical for its operation. PolarDB-X returns this error when an SQL statement attempts to modify data within these tables. The protected system tables include sequence, sequence_opt, and txc_undo_log. Do not use these reserved names for user-defined tables.

TDDL-4520 ERR_DML_WITH_SUBQUERY

Description: Subqueries are not supported in DML statements.
Example: ERR-CODE: [TDDL-4520][ERR_DML_WITH_SUBQUERY] DO NOT support UPDATE/DELETE with subQuery
Explanation: PolarDB-X prohibits subqueries within DML statements. To resolve this issue, rewrite the SQL statement to avoid using a subquery.

TDDL-4521 ERR_INSERT_SHARD

Description: A record maps to multiple shards during an INSERT operation.
Example: ERR-CODE: [TDDL-4521][ERR_INSERT_SHARD] Cannot decide which group to insert
This error occurs because the record maps to multiple shards, and the system cannot determine which one to use. If you encounter this issue, contact technical support.

TDDL-4523 ERR_TODNF_LIMIT_EXCEED

Description: The number of conditions in the WHERE clause exceeds the limit.
Example: ERR-CODE: [TDDL-4523][ERR_TODNF_LIMIT_EXCEED] toDnf has exceed the limit size
Explanation: PolarDB-X converts WHERE clause conditions to conjunctive normal form (CNF) and disjunctive normal form (DNF) for condition deduction and optimization. To ensure system stability, PolarDB-X limits the number of conditions to 2,000. You can increase this limit by adjusting the DNF_REX_NODE_LIMIT parameter.

TDDL-4524 ERR_TOCNF_LIMIT_EXCEED

Description: The number of conditions in the WHERE clause exceeds the limit.
Example: ERR-CODE: [TDDL-4524][ERR_TOCNF_LIMIT_EXCEED] toCnf has exceeded the limit
Explanation: To perform condition deduction and optimization, PolarDB-X converts query conditions in an SQL WHERE clause into conjunctive normal form (CNF) and disjunctive normal form (DNF). To ensure optimization stability, PolarDB-X limits the number of conditions to 2,000. You can increase this limit by adjusting the CNF_REX_NODE_LIMIT parameter.

TDDL-4526 ERR_FUNCTION_NOT_FOUND

Description: The specified function is not supported.
Example: ERR-CODE: [TDDL-4526][ERR_FUNCTION_NOT_FOUND] No match found for function signature
Note: This error occurs when the SQL query uses incorrect syntax or an unsupported function. Ensure the function call uses the correct number and type of parameters.

TDDL-4527 ERR_MODIFY_SHARD_COLUMN_ON_TABLE_WITHOUT_PK

You cannot modify the shard key on a table without a primary key.
Example: ERR-CODE: [TDDL-4527][ERR_MODIFY_SHARD_COLUMN_ON_TABLE_WITHOUT_PK]
Explanation: PolarDB-X does not support modifying the shard key on a table that does not have a primary key.

TDDL-4595 ERR_UNKNOWN_TZ

Description: The specified time zone is invalid.
Example: ERR-CODE: [TDDL-4595][ERR_UNKNOWN_TZ]
Note: Check the syntax and format of the specified time zone.

TDDL-4600 ERR_FUNCTION

Description: Invalid function call.
Example: ERR-CODE: [TDDL-4600][ERR_FUNCTION] function compute error by Incorrect parameter count in the call to native function '*****'
Note: This error indicates that a function call in an SQL query has incorrect syntax or parameters. Review the function call to verify that the parameter count and types are correct.

TDDL-4601 ERR_EXECUTOR

Example:

ERR-CODE: [TDDL-4601][ERR_EXECUTOR] only one column is supported in 
distinct aggregate

Explanation: This error indicates an internal failure within PolarDB-X during SQL execution, usually caused by an issue with the backend RDS MySQL instance.

TDDL-4602 ERR_CONVERTOR

Description: Invalid type conversion.
Example: ERR-CODE: [TDDL-4602][ERR_CONVERTOR] convertor error by Unsupported convert: [*****]
Explanation: This error occurs when PolarDB-X fails to convert a data type during SQL query execution. Inspect the SQL query for implicit type conversions and use matching data types for comparisons and calculations.

TDDL-4603 ERR_ACCROSS_DB_TRANSACTION

Description: A cross-database transaction failed.
Example: ERR-CODE: [TDDL-4603][ERR_ACCROSS_DB_TRANSACTION] Transaction accross db is not supported in current transaction policy, transaction node is: {0}, but this sql execute on: *****.
Note: Although PolarDB-X supports cross-database transactions by default, this error indicates that a different transaction policy has been set.

TDDL-4604 ERR_CONCURRENT_TRANSACTION

Description: Nested transactions are not supported.
Example: ERR-CODE: [TDDL-4604][ERR_CONCURRENT_TRANSACTION] Concurrent query is not supported on transaction group, transaction group is: {0}.
Explanation: PolarDB-X does not support nested transactions. This error occurs when you start a new transaction on a database connection that already has an active transaction.

To resolve this issue, avoid using nested transactions in your application logic. Alternatively, use an application-layer transaction framework to prevent nesting.

TDDL-4606: ERR_QUERY_CANCLED

Description: The current SQL statement was canceled.
Example: ERR-CODE: [TDDL-4606][ERR_QUERY_CANCLED] Getting connection is not allowed when query has been canceled, group is *****
Explanation: This error occurs when a KILL statement cancels an SQL statement. If this error occurs frequently, check if a client or program is issuing the KILL statement.

TDDL-4610 ERR_CONNECTION_CLOSED

Description: The connection has been closed.
Example: ERR-CODE: [TDDL-4610][ERR_CONNECTION_CLOSED] connection has been closed
Explanation: This error occurs when you attempt to reuse a closed database connection. A connection is closed if an SQL statement in a transaction fails or is canceled by the KILL command.

To resolve this issue, close the invalid connection and acquire a new one.

TDDL-4612 ERR_CHECK_SQL_PRIV

Description: The current account has insufficient permissions to execute the SQL statement.
Example: ERR-CODE: [TDDL-4612][ERR_CHECK_SQL_PRIV] check user ***** on db ***** sql privileges failed.
Explanation: New versions of PolarDB-X include an account authorization system similar to the permission system of MySQL. Only an account with the required permissions can execute the SQL statement. If an account does not have the required permissions, PolarDB-X returns the TDDL-4612 error.

To resolve this issue, check the account's PolarDB-X permissions. If insufficient, grant the required PolarDB-X permissions in the PolarDB-X console. Manage database accounts.

TDDL-4614 ERR_EXECUTE_ON_MYSQL

Description: This error occurs when an SQL statement fails to execute on a data node.
Example:
```
ERR-CODE: [TDDL-4614][ERR_EXECUTE_ON_MYSQL] Error occurs when execute on  GROUP '*****': Duplicate entry '*****' for key 'PRIMARY'
This error occurs when an SQL statement fails on a PolarDB-X data node. The end of the message shows the raw error from the data node. The following are common examples:
 
Duplicate entry '*****' for key 'PRIMARY'
A primary key conflict occurred when writing data to a data node table. To fix this, correct the data and run the statement again.
   
The table '*****' is full
This indicates that a temporary table on the data node is full. To fix this, increase the temporary tablespace or optimize the SQL statement.
     
Deadlock found when trying to get lock;
A deadlock occurred on the data node, often due to a high number of transaction conflicts during write operations.
```
Error with an INSERT INTO ... ON DUPLICATE KEY UPDATE statement
- Symptom: When you use an INSERT INTO ... ON DUPLICATE KEY UPDATE... statement to write data, you receive an error that resembles the following: Error occurs when execute on GROUP 'PROMOTION_P00000_GROUP' ATOM 'dskeyxxxxxxx000_group#pxc-xdb-s-xxxxxxxxxxx#x.x.x.x-3080#promotion_p00000': Duplicate entry '2024xxxxxxxx' for key 'uk_orderId'.
- Cause: The read committed (RC) isolation level does not use gap locks, so SELECT FOR UPDATE statements can return inaccurate results during concurrent operations. Modifying the partition key increases the response time, making this issue more likely.
- Solution: To fix this, change the database isolation level to repeatable read (RR). Removing the partition key from the UPSERT statement also significantly reduces the chance of this error.
Insertion error due to an auto-increment primary key
- Symptom: A data insertion fails with a primary key conflict error, even though the INSERT statement does not specify a value for the auto-increment primary key id. The SHOW CREATE TABLE statement shows that the next auto-increment value is 2900006, but the error is [179473d091c1a001][xxxx:3074][nationaltax]ERR-CODE: [TDDL-4614][ERR_EXECUTE_ON_MYSQL] Error occurs when execute on GROUP 'NATIOXXXXXGROUP' ATOM 'dskey_nationaltax_single_group#pxc-xdb-s-pxcxxxxxxqimhg2639#x.x.x.x-3001#nationaltax_single': Duplicate entry '200001' for key 'PRIMARY'.
- Cause: The SHOW SEQUENCE command displays the starting auto-increment value that is internally allocated by PolarDB-X. In contrast, the SHOW CREATE TABLE command for a non-partitioned table displays a value equal to the maximum value of the actual data in the table plus one. The error is reported because the auto-increment value for the problematic table is 200000. You can run the SHOW SEQUENCE command to view this value.
- Solution: Run ALTER SEQUENCE AUTO_SEQ_xxxxxxxx START WITH <max_id> to correct the sequence value. ALTER SEQUENCE.
UPDATE error on a table with a global secondary index (GSI)
- Symptom: Running UPDATE operations on certain tables can cause numerous primary key conflict errors like this: TDDL-4614 Error occurs when execute on GROUP 'JMXXXXXXXXXXX00000' ATOM 'dskey_xdafdsfads': Duplicate entry '3204347' for key 'PRIMARY'.
- Cause: The UPDATE statements that fail all involve modifying a partition key on a global secondary index.
- Solution: Drop the GSI on the table before running the UPDATE statement.
Note
For a local index on a partitioned table, you can think of the table as being divided into multiple physical tables based on the id partition key. A local index is a constraint on each physical table. This means that the unique constraint is effective within a physical table that contains rows with the same id partition key, but it is not effective at a global level. To ensure global uniqueness for the logical table, you must use a global secondary index (GSI), which increases write overhead. PolarDB-X can guarantee uniqueness for a single physical table on a DN, but it cannot guarantee global uniqueness across the entire PolarDB-X instance. You can create a GLOBAL UNIQUE INDEX to ensure global uniqueness.
Note: Refer to the original error message to troubleshoot TDDL-4614. Check the MySQL 5.6 documentation for MySQL error details. If the issue persists after ruling out application or data node problems, contact technical support.

TDDL-4616 ERR_UNKNOWN_DATABASE

Description: The specified database does not exist.
Example: ERR-CODE: [TDDL-4616][ERR_UNKNOWN_DATABASE] Unknown database '*****'
Explanation: PolarDB-X lets you specify a database name in a DDL statement. This error occurs if the specified name does not match the name of your PolarDB-X database.

To resolve this issue, modify the database name in the DDL statement to match the name of your PolarDB-X database.

TDDL-4620 ERR_FORBID_EXECUTE_DML_ALL

PolarDB-X forbids delete and update statements without a where clause.

TDDL-4633 ERR_DB_STATUS_READ_ONLY

Example: ERR-CODE: [TDDL-4633][ERR_DB_STATUS_READ_ONLY] Database is read-only, only read sql are supported
This error indicates that the database is read-only. Verify the permissions for the current account.

TDDL-4636 ERR_DDL_JOB_ERROR

A DDL statement failed to execute.

Example:

ERR-CODE: [TDDL-4636][ERR_DDL_JOB_ERROR] xxxx

To resolve this, see Handle DDL exceptions.

TDDL-4642 ERR_UNKNOWN_TABLE

This error means the specified table does not exist in the database.

Example:

ERR-CODE: [TDDL-4642][ERR_UNKNOWN_TABLE] Unknown table XX.XX

To resolve this issue, verify that the table exists in the current database.

TDDL-4707 ERR_OUT_OF_MEMORY

Description: A query exceeded the memory limit for a temporary table.
Example: ERR-CODE: [TDDL-4707][ERR_OUT_OF_MEMORY]
Explanation: To maintain database stability, PolarDB-X imposes a memory limit on temporary tables for each query. This error occurs when a query processing a large volume of data causes its temporary table to exceed the memory limit. To resolve this, enable the spill to disk feature or increase the memory limit for the query's temporary table.

TDDL-4709 ERR_IVENTORY_HINT_NOT_SUPPORT_CROSS_SHARD

Example: ERR-CODE: [TDDL-4709][ERR_IVENTORY_HINT_NOT_SUPPORT_CROSS_SHARD]
Explanation: The hot row optimization feature requires single-shard transactions. You will receive this error if a transaction using this feature becomes a cross-shard transaction. To resolve this issue, adjust your business logic to ensure the transaction remains within a single shard.

TDDL-4994 ERR_FLOW_CONTROL

Description: The request rate limit has been exceeded.
Example: ERR-CODE: [TDDL-4994][ERR_FLOW_CONTROL] [*****] flow control by *****
Explanation: This error indicates that PolarDB-X has reached its internal limit for processing SQL requests and is therefore rejecting the current request. Check for abnormal peaks in your SQL request volume. If the TDDL-4994 error persists even after your SQL request volume decreases, contact technical support.

TDDL-4998 ERR_NOT_SUPPORT

Description: The specified feature is not supported.
Example: ERR-CODE: [TDDL-4998][ERR_NOT_SUPPORT] ***** not support yet!
Note: This error indicates that the SQL syntax or feature in your statement is not supported by PolarDB-X. If your application requires this feature, contact technical support.

TDDL-5001 ERR_TRANS

Description: A general transaction error occurred.
Example: ERR-CODE: [TDDL-5001][ERR_TRANS] Too many lines updated in statement.
Explanation: Troubleshoot the error based on its specific message.
- Too many lines updated in statement
  
  This error occurs when the number of rows updated by an UPDATE statement in a transaction exceeds the limit of 1,000. Check the WHERE clause of the statement. If you need to update a large volume of data in a transaction, use the PolarDB-X hint/*TDDL:UNDO_LOG_LIMIT={number}*/ to adjust the limit.
- Deferred execution is only supported in Flexible or XA Transaction
  
  Deferred execution works only with the flexible transaction or XA transaction policy. Before you defer an execution using the PolarDB-X hint/*TDDL:DEFER*/, run the SET drds_transaction_policy = *** command to change the PolarDB-X transaction policy.
- For other error messages, contact technical support.

TDDL-5002 ERR_TRANS_UNSUPPORTED

Description: The transaction uses an unsupported syntax or feature.
Example: ERR-CODE: [TDDL-5002][ERR_TRANS_UNSUPPORTED] Table without primary keys is not supported.
Note: PolarDB-X does not support this feature in transactions. If you need this feature, contact technical support.

TDDL-5003 ERR_TRANS_LOG

Description: The transaction log cannot be accessed.
Example: ERR-CODE: [TDDL-5003][ERR_TRANS_LOG] Failed to update transaction state: *****
To ensure the atomicity of a distributed transaction, PolarDB-X accesses the transaction log on backend data nodes. The TDDL-5003 error occurs if PolarDB-X fails to read from or write to the transaction log.

A backend data node failure typically causes the TDDL-5003 error. Check the status and access load of the PolarDB-X backend data nodes. If the error persists after ruling out data node issues, contact technical support.

TDDL-5006 ERR_TRANS_COMMIT

Description: This error indicates that a transaction failed to commit.
Example: ERR-CODE: [TDDL-5006][ERR_TRANS_COMMIT] Failed to commit primary group *****: *****, TRANS_ID = *****
Explanation: This error occurs when PolarDB-X fails to commit a transaction branch. The system automatically rolls back the transaction identified by TRANS_ID. The typical cause is a backend data node failure. Check the status and access load of the backend data nodes in PolarDB-X. If the error persists after ruling out backend data node issues, contact technical support.

TDDL-5008 ERR_TRANS_TERMINATED

Description: A KILL statement or a timeout terminated the transaction.
Example: ERR-CODE: [TDDL-5008][ERR_TRANS_TERMINATED] Current transaction was killed or timeout. You may need to set a longer timeout value.
Explanation: This error occurs if a PolarDB-X transaction is terminated by a KILL statement or if its execution time exceeds the value of the drds_transaction_timeout parameter. If the error is caused by a transaction timeout, you can run the SET drds_transaction_timeout = *** command to increase the maximum execution time for PolarDB-X transactions. The value is specified in milliseconds.

TDDL-5010 ERR_TRANS_CONTINUE_AFTER_WRITE_FAIL

Description: A transaction cannot continue after a write operation fails.
Example: ERR-CODE: [TDDL-5010][ERR_TRANS_CONTINUE_AFTER_WRITE_FAIL] Cannot continue or commit transaction after writing failed
Note: When a write operation fails in a PolarDB-X distributed transaction, the transaction halts. You must issue a rollback command from the frontend to terminate the transaction before retrying. You can also use log analysis to troubleshoot slow transactions.

TDDL-5108 ERR_CHECK_PRIVILEGE_FAILED_ON_TABLE

Description: The current account lacks the required permissions for the specified table. Check the permissions granted to the account.

TDDL-5119 ERR_FILE_CANNOT_BE_CREATE

Description: Support for the SELECT INTO OUTFILE statement is disabled by default in PolarDB-X. To enable it, contact technical support.

TDDL-5302 ERR_GLOBAL_SECONDARY_INDEX_UNSUPPORTED

You cannot create a global secondary index on this table for one of the following reasons: 1. The table is a non-partitioned table or a broadcast table. 2. The columns of the global secondary index do not include the partition key. For any other reason, contact technical support.

TDDL-5306 ERR_GLOBAL_SECONDARY_INDEX_INSERT_DUPLICATE_VALUES

This error occurs when a write operation to a global secondary index table results in a primary key conflict. Check the record value in the error message to identify the conflicting record.

TDDL-5308 ERR_GLOBAL_SECONDARY_INDEX_MODIFY_UNIQUE_KEY

This error occurs when a DML operation causes a unique key conflict on a global secondary index. To resolve this, check the record value in the error message to identify the conflicting data.

TDDL-5310 ERR_GLOBAL_SECONDARY_INDEX_ONLY_SUPPORT_XA

PolarDB-X supports a global secondary index only with XA or Timestamp Oracle (TSO) distributed transactions. This error may occur if you have changed the default transaction policy. To resolve this issue, set the distributed transaction policy back to XA or TSO, and then create the global secondary index.

TDDL-5313 ERR_GLOBAL_SECONDARY_INDEX_MODIFY_GSI_TABLE_WITH_DDL

By default, PolarDB-X does not support DDL operations on global secondary index tables. To enable this capability, contact technical support.

TDDL-5316 ERR_GLOBAL_SECONDARY_INDEX_INDEX_AND_SHARDING_COLUMNS_NOT_MATCH

This error occurs because a PolarDB-X global secondary index must include all of its partition keys in the index columns. This rule applies to all partition keys, such as the database shard key and the table partition key. For example, the statement CREATE GLOBAL INDEX idx_1 ON t(a, b) DBPARTITION BY HASH(c) triggers the TDDL-5316 error. This occurs because the ON t(a, b) clause specifies a and b as index columns but omits the partition key, c. To resolve this error, update your DDL statement to ensure the index columns include all partition keys of the global secondary index.

TDDL-5317 ERR_GLOBAL_SECONDARY_INDEX_CONTINUE_AFTER_WRITE_FAIL

Example: ERR-CODE: [TDDL-5317][ERR_GLOBAL_SECONDARY_INDEX_CONTINUE_AFTER_WRITE_FAIL] Cannot continue or commit transaction after writing global secondary index failed
Description: If this error occurs when you execute a DML statement on a table with a global secondary index (GSI), you cannot commit the transaction containing the failed statement. You must modify your business code to roll back and then retry the transaction.

TDDL-5321 ERR_GLOBAL_SECONDARY_INDEX_BACKFILL_DUPLICATE_ENTRY

This error indicates that a duplicate primary key was found in the index table during data backfilling for a global secondary index.

TDDL-8007 ERR_ABANDONED_TASK

PolarDB-X returns this error when it terminates a query that is excessively slow or has been stuck for more than two hours. To resolve this issue, optimize your query. If the issue persists, contact technical support.

TDDL-8008 ERR_EXECUTE_SPILL

Large intermediate query results can cause a temporary table to spill to disk. This error indicates that an exception occurred during the spill-to-disk process. Contact technical support.

TDDL-8011 ERR_OUT_OF_SPILL_SPACE

During query execution, large intermediate results can cause temporary tables to flush to disk. This error occurs when these files exceed the maximum disk space for spilling. To resolve this, optimize the query to minimize the use of temporary tables. If the issue persists, contact technical support.

TDDL-8012 ERR_OUT_OF_SPILL_FD

During query execution, large intermediate results can cause a temporary table to flush to disk. This error occurs if the temporary table generates more files than the system's file handle limit. Contact technical support to investigate a potential file handle leak. If no leak is found, you can increase the file handle limit as needed.

TDDL-8102 ERR_PAGE_TOO_LARGE

This error occurs during massively parallel processing (MPP) when a data batch exchanged between compute nodes exceeds the remote procedure call (RPC) size limit. To resolve this issue, reduce the default CHUNK_SIZE.

TDDL-8103 ERR_NO_NODES_AVAILABLE

Description: This error indicates that no compute nodes are available for task scheduling, possibly due to a compute node failure during MPP parallel computing. To resolve this, verify that all compute node services are running correctly. If the error persists, contact technical support.

TDDL-9301 ERR_DUPLICATED_PARTITION_NAME

This error occurs when a DDL statement uses a duplicate partition name.

TDDL-9305 ERR_PARTITION_NAME_NOT_EXISTS

This error occurs when a DDL operation on a partitioned table specifies a partition name that does not exist. Verify that the partition name is spelled correctly. Run show create table and check table to check for metadata consistency. Inconsistent metadata can cause this error. If the issue persists, contact technical support.

TDDL-10004 ERR_X_PROTOCOL_RESULT

Example: ERR-CODE: [TDDL-10004][ERR_X_PROTOCOL_RESULT] Should use chunk2chunk to fetch data
Explanation: In PolarDB-X, compute nodes use private RPC to communicate with data nodes. This error indicates a failed connection between a compute node and a data node. This issue has several potential causes. Check the error message for more details. If you cannot identify the root cause, contact technical support.