typeorm

Postconditions — what we check

• find · find-query-error

  error
  Whenquery fails (connection lost, invalid relation, timeout, syntax error)
  ThrowsQueryFailedError or connection error
  Required handlingCaller MUST wrap repository.find() in try-catch to handle database errors. Connection failures and invalid queries crash application if unhandled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• save · save-constraint-violation

  error
  Whensave violates constraint (unique, foreign key, validation, type mismatch)
  ThrowsQueryFailedError with constraint violation details
  Required handlingCaller MUST wrap save() in try-catch to handle constraint violations and validation errors. Unique violations, foreign key errors, and validation failures crash application if unhandled.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• transaction · transaction-error

  error
  Whenoperation within transaction fails (constraint violation, deadlock, connection lost)
  ThrowsError causing automatic rollback
  Required handlingCaller MUST wrap transaction operations in try-catch to handle errors and ensure rollback. Unhandled errors leave database in inconsistent state if transaction partially commits.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• findOne · findone-query-failed-error

  error
  WhenDatabase query fails (connection lost, invalid relations, timeout)
  ThrowsQueryFailedError (extends TypeORMError) with driverError containing underlying DB error
  Required handlingCaller MUST wrap in try-catch to handle database errors. findOne() returns null when not found — no need to handle EntityNotFoundError here. Distinguish null result (not found) from thrown error (DB failure) in caller logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][5]
• findOneBy · findoneby-query-failed-error

  error
  WhenDatabase query fails (connection lost, invalid column, timeout)
  ThrowsQueryFailedError with driverError containing underlying DB error
  Required handlingCaller MUST wrap in try-catch. A null return means not found (not an error). A thrown QueryFailedError means the DB operation failed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• findOneOrFail · findone-or-fail-entity-not-found

  error
  WhenNo entity matches the given find options
  ThrowsEntityNotFoundError (extends TypeORMError) — message includes entity name and criteria
  Required handlingCaller MUST wrap in try-catch and handle EntityNotFoundError. Import EntityNotFoundError from 'typeorm' for type-safe instanceof checks. Distinguish from QueryFailedError (DB failure) vs EntityNotFoundError (not found). This is the GUARANTEED throw path — do not use findOneOrFail() without a catch block.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][7]
• findOneOrFail · findone-or-fail-query-failed

  error
  WhenDatabase query fails (connection lost, timeout, invalid schema)
  ThrowsQueryFailedError with driverError containing the underlying DB error
  Required handlingCaller MUST also handle QueryFailedError separately from EntityNotFoundError. Two distinct failure modes: entity not found vs DB failure.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• findOneByOrFail · findonebyorfail-entity-not-found

  error
  WhenNo entity matches the WHERE conditions
  ThrowsEntityNotFoundError (extends TypeORMError) — always thrown when no result found
  Required handlingCaller MUST wrap in try-catch. EntityNotFoundError has entityClass and criteria properties for context. This is the preferred pattern over findOneBy() + manual null check when entity MUST exist.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• insert · insert-duplicate-key-error

  error
  WhenUnique constraint or primary key violation (duplicate insert)
  ThrowsQueryFailedError with driverError.code = 'ER_DUP_ENTRY' (MySQL), '23505' (PostgreSQL), 'SQLITE_CONSTRAINT' (SQLite)
  Required handlingCaller MUST wrap in try-catch. Check error.driverError.code for database-specific constraint violation codes. insert() is intentionally primitive — no upsert logic. Use upsert() for idempotent inserts. Unlike save(), insert() will not merge existing entities — always throws on duplicate PK.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4][5]
• insert · insert-foreign-key-violation

  error
  WhenForeign key constraint violation (referenced entity does not exist)
  ThrowsQueryFailedError with driverError containing FK violation details
  Required handlingCaller MUST validate referenced entity existence before insert. Or wrap in try-catch and handle FK error from driverError.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4]
• update · update-constraint-violation

  error
  WhenUpdate violates unique constraint or type mismatch
  ThrowsQueryFailedError with driverError containing constraint violation details
  Required handlingCaller MUST wrap in try-catch to handle constraint violations. Also check UpdateResult.affected to verify rows were actually updated — TypeORM does NOT throw if criteria match 0 rows.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4][5]
• update · update-silent-no-op

  warning
  WhenCriteria matches 0 rows — update silently affects nothing
  ThrowsDoes not throw — UpdateResult.affected === 0
  Required handlingCaller SHOULD check UpdateResult.affected after update(). If affected === 0, entity did not exist — decide whether to create or error. Typical bug: assume update succeeded without checking affected count.
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[5]
• delete · delete-foreign-key-constraint

  error
  WhenDelete violates foreign key constraint (other records reference this entity)
  ThrowsQueryFailedError with driverError containing FK constraint details
  Required handlingCaller MUST wrap in try-catch to handle FK constraint violations. Check driverError.code for database-specific FK codes (MySQL: ER_ROW_IS_REFERENCED_2, Postgres: 23503). Consider using cascade:true in entity relations or deleting dependent records first.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][5]
• delete · delete-silent-no-op

  warning
  WhenCriteria matches 0 rows — delete silently affects nothing
  ThrowsDoes not throw — DeleteResult.affected === 0
  Required handlingCaller SHOULD check DeleteResult.affected after delete(). If business logic requires entity to exist, use findOneOrFail() first.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[5]
• upsert · upsert-constraint-violation

  error
  WhenForeign key violation or non-conflict unique constraint violated by upsert
  ThrowsQueryFailedError with driverError containing constraint violation details
  Required handlingCaller MUST wrap in try-catch. Conflict resolution only handles the specified conflictPaths — other constraints still throw. Check driverError.code for database-specific constraint codes.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4][5]
• query · query-sql-syntax-error

  error
  WhenSQL query has syntax error or references non-existent table/column
  ThrowsQueryFailedError with driverError containing the SQL error details and the original query
  Required handlingCaller MUST wrap in try-catch. QueryFailedError.query contains the SQL that failed — useful for debugging. QueryFailedError.driverError contains database-specific error code and message.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][5]
• query · query-sql-injection-risk

  error
  WhenUser input interpolated directly into SQL string (not using parameterized query)
  ThrowsDoes not throw — silently allows SQL injection
  Required handlingALWAYS use parameterized queries: repository.query('SELECT * FROM users WHERE id = $1', [userId]) NEVER concatenate user input into SQL: repository.query(`SELECT * FROM users WHERE id = ${userId}`) SQL injection can exfiltrate entire database or destroy all data.
  costhighin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[5]
• softDelete · softdelete-missing-delete-date-column

  error
  WhenEntity does not have a @DeleteDateColumn() decorated field
  ThrowsMissingDeleteDateColumnError (extends TypeORMError) — entity name included in message
  Required handlingEnsure entity class has @DeleteDateColumn() column before calling softDelete(). Add column: @DeleteDateColumn() deletedAt: Date This error occurs at runtime — schema mismatch between entity definition and usage.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• softDelete · softdelete-silent-no-op

  warning
  WhenCriteria matches 0 rows — softDelete silently affects nothing
  ThrowsDoes not throw — UpdateResult.affected === 0
  Required handlingCheck UpdateResult.affected to verify rows were actually soft-deleted.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[5]
• restore · restore-missing-delete-date-column

  error
  WhenEntity does not have @DeleteDateColumn() decorated field
  ThrowsMissingDeleteDateColumnError (extends TypeORMError)
  Required handlingEnsure entity has @DeleteDateColumn() before calling restore(). Same configuration requirement as softDelete().
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• remove · remove-foreign-key-constraint

  error
  WhenFK constraint violation on entity or cascaded entities
  ThrowsQueryFailedError with driverError containing FK constraint details
  Required handlingCaller MUST wrap in try-catch. Unlike delete(), remove() processes relations — cascade errors surface here. Ensure all dependent records are handled (deleted or reassigned) before removing.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4]
• count · count-query-failed-error

  error
  WhenDatabase query fails (connection lost, invalid relations, timeout)
  ThrowsQueryFailedError with driverError containing the database error
  Required handlingCaller MUST wrap in try-catch. Pagination logic that depends on count() can expose incorrect totals if errors are swallowed.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• findBy · findby-query-failed-error

  error
  WhenDatabase query fails (connection lost, invalid column, timeout)
  ThrowsQueryFailedError with driverError
  Required handlingCaller MUST wrap in try-catch. Empty array is a valid result — not an error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• findAndCount · findandcount-query-failed-error

  error
  WhenEither the find or count query fails (connection lost, timeout)
  ThrowsQueryFailedError with driverError
  Required handlingCaller MUST wrap in try-catch. A failed findAndCount() leaves pagination state undefined — do not cache partial results. Common pagination pattern: never silently fall back to page 1 on error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• increment · increment-type-mismatch

  error
  WhenColumn is not numeric or propertyPath does not exist on entity
  ThrowsQueryFailedError or TypeORMError with type mismatch details
  Required handlingCaller MUST wrap in try-catch. Ensure propertyPath is a numeric @Column — calling increment() on a string column throws at runtime. Also check UpdateResult.affected — silent no-op if criteria matches 0 rows.
  costlowin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4][5]
• decrement · decrement-type-mismatch

  error
  WhenColumn is not numeric, propertyPath does not exist, or check constraint violated
  ThrowsQueryFailedError or TypeORMError
  Required handlingCaller MUST wrap in try-catch. Database-level check constraints (e.g., balance >= 0) will throw QueryFailedError on violation. Application-level guard: ensure value is > 0 before decrementing counters/balances.
  costlowin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[4]
• initialize · initialize-already-connected

  error
  WhenDataSource.initialize() called when DataSource is already initialized (isInitialized === true)
  ThrowsCannotConnectAlreadyConnectedError (extends TypeORMError)
  Required handlingCheck dataSource.isInitialized before calling initialize(). Or guard with: if (!dataSource.isInitialized) await dataSource.initialize() Common bug: initializing inside request handlers (called on every request).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][10]
• initialize · initialize-connection-failure

  error
  WhenCannot connect to database (wrong credentials, host unreachable, invalid connection string)
  ThrowsError from underlying database driver (propagated through DataSource, destroys partial state)
  Required handlingCaller MUST wrap in try-catch and handle startup failure gracefully. A failed initialize() should stop application startup — log error and exit. Re-throwing is acceptable at startup boundary; silently swallowing means no DB access but no visible error.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][11]
• destroy · destroy-not-initialized

  warning
  WhenDataSource.destroy() called when DataSource is not initialized
  ThrowsCannotExecuteNotConnectedError (extends TypeORMError)
  Required handlingCheck dataSource.isInitialized before calling destroy(). Pattern: if (dataSource.isInitialized) await dataSource.destroy() Common in test teardown or graceful shutdown handlers.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9][12]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]typeorm.io/find-optionshttps://typeorm.io/find-options
2. [2]typeorm.io/repository-apihttps://typeorm.io/repository-api
3. [3]typeorm.io/transactionshttps://typeorm.io/transactions
4. [4]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/error/QueryFailedError.ts
5. [5]typeorm.io/docs/working-with-entity-managerhttps://typeorm.io/docs/working-with-entity-manager/repository-api
6. [6]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/error/EntityNotFoundError.ts
7. [7]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/entity-manager/EntityManager.ts
8. [8]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/error/MissingDeleteDateColumnError.ts
9. [9]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/data-source/DataSource.ts
10. [10]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/error/CannotConnectAlreadyConnectedError.ts
11. [11]typeorm.io/docs/data-sourcehttps://typeorm.io/docs/data-source/data-source-api
12. [12]raw.githubusercontent.com/typeorm/typeormhttps://raw.githubusercontent.com/typeorm/typeorm/master/src/error/CannotExecuteNotConnectedError.ts