Ecto Constraint Debugging

Ecto Constraint Debugging

Ash projects: Ash surfaces DB constraints through its own error DSL. Use the ash-framework skill — mix usage_rules.search_docs "constraint" -p ash_postgres.

Systematic approach to diagnosing constraint violations. Load when you see Ecto.ConstraintError, unique_constraint, foreign_key_constraint, or constraint-related changeset errors.

Iron Laws

1. READ THE CONSTRAINT NAME — The constraint name (e.g., links_url_index) tells you exactly which index/constraint failed. Parse it from the error message first
2. CHECK MIGRATION BEFORE CODE — Verify the constraint definition in priv/repo/migrations/ matches what the schema expects
3. TRACE ALL INSERT PATHS — Find every code path that inserts into the constrained table. The bug is often in a path you didn't consider
4. RACE CONDITION UNTIL PROVEN OTHERWISE — If validation passes but constraint fails, assume concurrent inserts until you prove a single-request cause

Step-by-Step Debugging

Step 1: Parse the Error

Extract from the error message:

• Constraint name (e.g., users_email_index)
• Table name (e.g., users)
• Operation (insert, update, or delete)
• Conflicting values (if available in logs)

Step 2: Find the Migration

Use Grep to search for the constraint name in priv/repo/migrations/. Also check for create unique_index, create index, add constraint.

Verify: Does the migration constraint match the schema's unique_constraint/3 or foreign_key_constraint/3 call?

Step 3: Find the Schema

Use Grep to find constraint handling in changesets (unique_constraint, foreign_key_constraint, check_constraint) in lib/.

Step 4: Trace Insert Paths

Find ALL callers that insert/update this schema:

Use Grep to find all insert/update paths (Repo.insert, Repo.update, Repo.insert_all, cast_assoc) in lib/.