Library-Raised Errors

This page covers TsSqlError reasons raised directly by ts-sql-query outside the native database mapping tables. It is meant as a lookup page for errors produced by query construction, value conversion, transaction orchestration, dynamic conditions, mocks, and library guards.

Some reasons in this page can also be produced by query runners when a driver reports an equivalent condition. In those cases, the driver code, number, and message are documented in the native mapping pages.

Library-raised errors

Category	Reason	Diagnosis	Filled fields
Query rules	DISALLOWED_BY_QUERY_RULE	Meaning A configured query rule rejected a property or row. Check the rule message and the rejected property first. Typical source Insert and update builders applying per-column or per-property allow/disallow rules.	message disallowedProperty optional disallowedRowIndex
Query rules	DISALLOWED functionName allowWhen	Meaning An expression, raw fragment, aggregate helper, or value source was disabled by allowWhen. The message comes from the error text provided to allowWhen. Typical source allowWhen helpers in value sources, table/view raw fragments, and aggregate value sources.	message functionName
Query rules	DISALLOWED functionName disallowWhen	Meaning An expression, raw fragment, aggregate helper, or value source was blocked by disallowWhen. The message comes from the error text provided to disallowWhen. Typical source disallowWhen helpers in value sources, table/view raw fragments, and aggregate value sources.	message functionName
Query validation	ORDER_BY_COLUMN_NOT_IN_SELECT	Meaning A string-based order by references a column that is not part of the select result. Typical source Select builders using string order-by helpers.	column
Query validation	INVALID_ORDER_BY_ORDERING	Meaning A string-based order by uses an unsupported ordering token. Typical source Select builders using string order-by helpers.	column ordering
Query validation	MISSING_WHERE	Meaning A protected update or delete was built without the required where clause. Typical source Mutation builders with safety checks enabled.	-
Query validation	INVALID_SHAPE_OVERRIDE	Meaning A shape extension attempts to define a property that already exists. Typical source Shape extension and result shaping helpers.	property
Query validation	NO_COLUMN_SETS	Meaning An update has no columns to set. Typical source Update builders before SQL generation.	-
Query validation	CONSTANT_VALUES_VIEW_CANNOT_BE_EMPTY	Meaning A constant values view was created with zero rows. Typical source Constant values view builder.	-
Query validation	UNSUPPORTED_QUERY	Meaning The requested operation or generated query shape is not supported by the selected database dialect. Typical source Dialect-specific SQL builders and query runner capability checks.	-
Query validation	ONLY_ONE_COLUMN_EXPECTED	Meaning A one-column operation received or produced more than one result column. Typical source Result processing for one-column select or returning helpers.	-
Query validation	OUT_PARAMS_NOT_SUPPORTED	Meaning An out parameter was requested for a database that does not support out params. Typical source Query builder or connection APIs involving out params.	-
Query validation	UNSUPPORTED_DATABASE	Meaning A connection or query runner was asked to use an incompatible database type. Typical source Query runner useDatabase guards.	database
SQL construction	UNKNOWN_DATA_TYPE	Meaning A value source type is unknown to the SQL builder. If present, inspect typeName to find the unsupported type. Typical source SQL builders and value source type resolution.	optional typeName
SQL construction	INVALID_SQL_FRAGMENT_RETURN_TYPE	Meaning A custom SQL fragment returned something that is not a valid SQL element for that position. Typical source Fragment value source helpers.	typeName
Execution result	MINIMUM_ROWS_NOT_REACHED	Meaning A mutation affected fewer rows than the execution helper required. Typical source Execution helpers with minimum affected-row checks.	count min
Execution result	MAXIMUM_ROWS_EXCEEDED	Meaning A mutation affected more rows than the execution helper allowed. Typical source Execution helpers with maximum affected-row checks.	count max
Execution result	MORE_THAN_ONE_ROW	Meaning A one-row operation received multiple rows. Typical source Single-row select, insert, update, delete, or returning helpers.	count
Execution result	NO_RESULT	Meaning A required row or scalar value was not returned. Typical source Required-result execution helpers and function calls.	-
Value conversion	INVALID_VALUE_TO_SEND_TO_DATABASE	Meaning A TypeScript value cannot be serialized to the declared database type. Check typeName, columnPath, and the offending value. Typical source Connection value adapters before parameters are sent to the driver.	value typeName optional rowIndex optional columnPath
Value conversion	INVALID_VALUE_RECEIVED_FROM_DATABASE	Meaning A database value cannot be converted to the requested TypeScript type. Check whether the selected column type matches the real returned value. Typical source Result conversion in connections and query builders.	value typeName optional rowIndex optional columnPath
Value conversion	MANDATORY_VALUE_NOT_RECEIVED_FROM_DATABASE	Meaning A mandatory value was received as null or undefined. Typical source Result conversion for mandatory columns, generated ids, and function returns.	value typeName optional rowIndex optional columnPath
Value conversion	INVALID_JSON_RECEIVED_FROM_DATABASE	Meaning A JSON value from the database could not be parsed or did not arrive in the expected shape. Typical source JSON result conversion and SQL Server JSON handling.	value typeName optional rowIndex optional columnPath
Transaction	TRANSACTION_ERROR transactionErrorType invalid state aborted active transaction serialization failure deadlock transaction rolled back outcome unknown invalid savepoint unsupported operation	Meaning A transaction failure was normalized by a query runner or transaction engine. Use transactionErrorType for the semantic class and the native pages for database-specific signals. Typical source Transaction begin, commit, rollback, savepoint, and native mapper paths.	optional transactionErrorType optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Transaction	NESTED_TRANSACTION_NOT_SUPPORTED	Meaning A nested transaction was requested on a runner that does not support it. Typical source Connection transaction guards and query runners without nested transaction support.	optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Transaction	NOT_IN_TRANSACTION	Meaning A transaction-only action was requested without an active transaction. Typical source Commit, rollback, deferred transaction, and connection configuration guards.	optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Transaction	NESTED_DEFERRING_IN_TRANSACTION_NOT_SUPPORTED	Meaning A deferred transaction callback was registered from inside another deferred transaction callback. Typical source executeBeforeNextCommit, executeAfterNextCommit, and executeAfterNextRollback guards.	-
Transaction	ERROR_EXECUTING_DEFERRED_IN_TRANSACTION deferredType before next commit	Meaning A before next commit deferred callback failed. The wrapped cause is the original callback error. Typical source Deferred transaction callback execution.	fn index deferredType
Transaction	ERROR_EXECUTING_DEFERRED_IN_TRANSACTION deferredType after next commit	Meaning An after next commit deferred callback failed. The wrapped cause is the original callback error. Typical source Deferred transaction callback execution.	fn index deferredType
Transaction	ERROR_EXECUTING_DEFERRED_IN_TRANSACTION deferredType after next rollback	Meaning An after next rollback deferred callback failed. The wrapped cause is the original callback error. Typical source Deferred transaction callback execution.	fn index deferredType
Transaction	LOW_LEVEL_TRANSACTION_NOT_SUPPORTED	Meaning Low-level transaction methods were requested on a runner that cannot expose them. Typical source Query runner transaction APIs, notably delegated or high-level runners.	optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Transaction	TRANSACTION_LEVEL_NOT_SUPPORTED	Meaning The requested isolation level is not supported by the current runner or database. Typical source Transaction begin helpers and query runner transaction configuration.	transactionLevel optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Transaction	TRANSACTION_ACCESS_MODE_NOT_SUPPORTED	Meaning The requested transaction access mode is not supported by the current runner or database. Typical source Transaction begin helpers and query runner transaction configuration.	accessMode optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Runtime usage	FORBIDDEN_CONCURRENT_USAGE	Meaning The same connection or query runner is being used concurrently where exclusive use is required. Typical source Transaction guards, pool connection acquisition, and some driver-specific concurrent-use checks.	optional databaseErrorCode optional databaseErrorNumber optional databaseErrorMessage
Dynamic conditions	DYNAMIC_CONDITION_INVALID_FILTER	Meaning A dynamic filter has the wrong shape for the current path. Check path to locate the invalid branch. Typical source Dynamic condition builder.	value path
Dynamic conditions	DYNAMIC_CONDITION_INVALID_EXTENSION_RETURN_TYPE	Meaning A dynamic condition extension or operation returned a value that is not a boolean value source. Typical source Dynamic condition extensions and custom operations.	processedValue returnedValue optional returnedTypeName path extensionName
Dynamic conditions	DYNAMIC_CONDITION_UNKNOWN_COLUMN	Meaning A dynamic condition references a column not present in the allowed column map. Typical source Dynamic condition builder.	path
Dynamic conditions	DYNAMIC_CONDITION_UNKNOWN_OPERATION	Meaning A dynamic condition uses an operation name not supported by that column or extension set. Typical source Dynamic condition builder.	path name
Metadata validation	GROUP_BY_COLUMN_NOT_IN_SELECT	Meaning A group-by references a column outside the select list. Typical source Query validation normally prevented by TypeScript.	column
Metadata validation	COLUMN_FOR_INSERT_COMING_FROM_SUBQUERY_NOT_IN_TABLE	Meaning An insert-from-select column does not exist in the target table. Typical source Insert query validation.	column
Metadata validation	MAPPED_SHAPED_COLUMN_NOT_IN_TABLE	Meaning A shaped column mapping points to a column outside the target table. Typical source Shape/table mapping validation.	shapeProperty mappedTo
Metadata validation	NO_AUTOGENERATED_ID_COLUMN_FOUND	Meaning An autogenerated id was expected but no such column is configured. Typical source Insert-returning-id helpers.	-
Metadata validation	NO_PRIMARY_KEY_FOUND	Meaning A primary key was expected but not found in the table metadata. Typical source Update/delete helpers relying on primary keys.	-
Configuration	INVALID_CONFIGURATION	Meaning A library, connection, or query runner option has an invalid value. Typical source Connection configuration and driver-specific query runner configuration guards.	name value
Mocking	INVALID_MOCKED_VALUE queryType selectOneRow selectManyRows selectOneColumnManyRows	Meaning A select mock returned the wrong shape. Select one-row mocks expect null, undefined, or a plain object; many-row mocks expect arrays with the right element shape. Typical source MockQueryRunner select methods.	value queryType index
Mocking	INVALID_MOCKED_VALUE queryType insert insertReturningMultipleLastInsertedId insertReturningOneRow insertReturningManyRows insertReturningOneColumnManyRows	Meaning An insert mock returned the wrong shape. Plain inserts expect an affected-row count; returning variants expect ids, objects, or arrays depending on the query type. Typical source MockQueryRunner insert methods.	value queryType index
Mocking	INVALID_MOCKED_VALUE queryType update updateReturningOneRow updateReturningManyRows updateReturningOneColumnManyRows	Meaning An update mock returned the wrong shape. Plain updates expect an affected-row count; returning variants expect objects or arrays depending on the query type. Typical source MockQueryRunner update methods.	value queryType index
Mocking	INVALID_MOCKED_VALUE queryType delete deleteReturningOneRow deleteReturningManyRows deleteReturningOneColumnManyRows	Meaning A delete mock returned the wrong shape. Plain deletes expect an affected-row count; returning variants expect objects or arrays depending on the query type. Typical source MockQueryRunner delete methods.	value queryType index
Mocking	INVALID_MOCKED_VALUE queryType executeProcedure beginTransaction commit rollback isTransactionActive executeDatabaseSchemaModification executeConnectionConfiguration	Meaning A mock for procedure execution, transaction control, transaction state, schema modification, or connection configuration returned the wrong shape. Typical source MockQueryRunner procedure, transaction, schema, and connection-configuration methods.	value queryType index
Expression evaluation	EXPRESSION_IS_NOT_CONST	Meaning Code tried to read a constant value from an expression that is not constant. Typical source Value source constant evaluation.	-
Synchronous execution	SYNCHRONOUS_PROSIME_EXPECTED	Meaning A real async promise was produced inside a synchronous database flow. Typical source Synchronous query execution helpers.	-
Fallback	UNKNOWN	Meaning A query runner caught a value it does not recognize as a SQL error or a library error. Inspect the original cause for the raw thrown value. Typical source Query runner fallback paths.	-

Mocking and the projector pipeline

INVALID_MOCKED_VALUE is a shape gate on the value the user-supplied queryExecutor returns to MockQueryRunner for the given queryType (e.g. a plain object for a single-row select, an array of plain objects for a many-row select, a number for affected-row counts). Past that gate the value flows through the same result-projection pipeline a real driver's response would, so the mock is impersonating a database response from then on. A structurally valid row that omits a column the select({...}) projects as required produces MANDATORY_VALUE_NOT_RECEIVED_FROM_DATABASE, a value with the wrong runtime type produces INVALID_VALUE_RECEIVED_FROM_DATABASE, and an unparseable JSON-aggregated column produces INVALID_JSON_RECEIVED_FROM_DATABASE — the same reasons that would fire against a real driver returning the same payload. That is the documented invariant; the fix in test code is to include every projected column in the mocked row (or to seed [] / undefined when the test only asserts the emitted SQL).

Internal invariant errors

INTERNAL means a ts-sql-query invariant failed. These errors normally point to a library bug, an impossible state, an advanced integration implemented incorrectly, or unexpected internal data. They are not intended to be handled as ordinary user input or database failures.

Category	Reason	Diagnosis	Filled fields
Internal	INTERNAL internalErrorType illegal state	Meaning A builder reached a state that should not be reachable through the public API. Typical source Select, insert, update, and delete builder state transitions.	internalErrorType
Internal	INTERNAL internalErrorType invalid result column	Meaning A result column is missing or is not a valid value source where one is required. Typical source Select, insert, update, delete, and SQL builder result-column checks.	internalErrorType
Internal	INTERNAL internalErrorType unable to discover optional joins	Meaning Optional join discovery could not converge. Typical source Select builder optional join discovery.	internalErrorType
Internal	INTERNAL internalErrorType invalid compound operator	Meaning A SQL compound operator is not one of the supported internal operators. Typical source SQL builders handling compound queries.	internalErrorType operator
Internal	INTERNAL internalErrorType invalid join type	Meaning A join type is not one of the supported internal join kinds. Typical source SQL builders rendering joins.	internalErrorType joinType
Internal	INTERNAL internalErrorType invalid out binds returned	Meaning The database driver returned out-bind data in an unexpected shape. Typical source Oracle query runner out-bind processing.	internalErrorType value
Internal	INTERNAL internalErrorType expecting insert of multiple values	Meaning SQL generation expected a multi-values insert shape but received a different internal insert shape. Typical source SQL builders rendering multi-row insert statements.	internalErrorType
Internal	INTERNAL internalErrorType expecting insert from select	Meaning SQL generation expected an insert-from-select shape but received a different internal insert shape. Typical source SQL builders rendering insert-from-select statements.	internalErrorType
Internal	INTERNAL internalErrorType invalid value source	Meaning A value source implementation does not provide the internal SQL rendering method required for its position. Typical source SQL builder condition rendering and advanced value source integrations.	internalErrorType
Internal	INTERNAL internalErrorType incomplete old value query	Meaning Old-value emulation lacks required columns or aliases. Typical source SQL builders creating old-value emulation queries for update/delete strategies.	internalErrorType
Internal	INTERNAL internalErrorType repeated column	Meaning The same output column path appears where repeated columns are not allowed. Typical source SQL builder result column name validation.	internalErrorType columnPath
Internal	INTERNAL internalErrorType unexpected value	Meaning An internal value appeared in a place where the builder explicitly expects none. Typical source Value source handling of inline select or aggregated array paths.	internalErrorType