go-gorm/gorm · error

violates check constraint

Error message

violates check constraint

What it means

ErrCheckConstraintViolated is GORM's translated sentinel error for a database CHECK constraint violation. When gorm.Open is configured with TranslateEnabled: true, a driver error like PostgreSQL's '23514 violates check constraint' is rewritten to this error so callers can match it with errors.Is. It means the INSERT or UPDATE you ran produced column values that fail a CHECK constraint defined on the table (e.g. CHECK (price >= 0)).

Source

Thrown at errors.go:53

	ErrInvalidField = errors.New("invalid field")
	// ErrEmptySlice empty slice found
	ErrEmptySlice = errors.New("empty slice found")
	// ErrDryRunModeUnsupported dry run mode unsupported
	ErrDryRunModeUnsupported = errors.New("dry run mode unsupported")
	// ErrInvalidDB invalid db
	ErrInvalidDB = errors.New("invalid db")
	// ErrInvalidValue invalid value
	ErrInvalidValue = errors.New("invalid value, should be pointer to struct or slice")
	// ErrInvalidValueOfLength invalid values do not match length
	ErrInvalidValueOfLength = errors.New("invalid association values, length doesn't match")
	// ErrPreloadNotAllowed preload is not allowed when count is used
	ErrPreloadNotAllowed = errors.New("preload is not allowed when count is used")
	// ErrDuplicatedKey occurs when there is a unique key constraint violation
	ErrDuplicatedKey = errors.New("duplicated key not allowed")
	// ErrForeignKeyViolated occurs when there is a foreign key constraint violation
	ErrForeignKeyViolated = errors.New("violates foreign key constraint")
	// ErrCheckConstraintViolated occurs when there is a check constraint violation
	ErrCheckConstraintViolated = errors.New("violates check constraint")
)

View on GitHub (pinned to 1d6ce99528)

Solutions

  1. Fix the data being written so it satisfies the constraint (usually a validation gap in the application layer).
  2. Inspect the constraint in the DB (\d table or SHOW CREATE TABLE) to confirm which CHECK fires and on which column.
  3. If the business rule changed, drop or alter the constraint via a migration before writing the new data.
  4. If pre-existing rows violate it, run a data-cleanup UPDATE before re-enabling/enforcing the constraint.

Example fix

// before
db.Create(&Order{Price: -5}) // violates CHECK (price >= 0)

// after
if order.Price < 0 {
    return errors.New("price must be non-negative")
}
db.Create(&order)
Defensive patterns

Strategy: try-catch

Validate before calling

func validPrice(p int) bool { return p >= 0 }
// before write:
if !validPrice(order.Price) { return ErrValidation }

Type guard

func isCheckViolation(err error) bool { return errors.Is(err, gorm.ErrCheckConstraintViolated) }

Try / catch

err := db.Create(&order).Error
if err != nil {
    if errors.Is(err, gorm.ErrCheckConstraintViolated) {
        // map to 422 validation error, log the offending record
    }
    return err // real DB failure
}

Prevention

When it happens

Trigger: Inserting or updating a row whose column value breaks a CHECK constraint - either one declared via the gorm tag `gorm:"check:price>0"` (created by AutoMigrate) or one already defined in the DB - while the connection has error translation enabled (gorm.Open(dia, &gorm.Config{TranslateEnabled: true})).

Common situations: Adding a `check:` gorm tag to an existing model and then writing legacy/edge data (negative amounts, empty strings on CHECK (name <> '')); backfilling historical rows that predate the constraint; test fixtures generated with zero values that violate non-zero checks; MySQL 8 / PostgreSQL / SQLite behaving differently on constraint enforcement so the bug appears only in one environment.

Related errors

AI-assisted analysis of go-gorm/gorm@1d6ce99528 (2026-08-15). Data as JSON: /api/errors/b9318ebd51663d24. Report an issue: GitHub.