// Referencia de errores de SQLite

SQLITE_CONSTRAINT_FOREIGNKEY: Falló la restricción FOREIGN KEY

La escritura dejaría una fila hija apuntando a un padre que no existe, o borraría un padre que aún tiene hijos. Las claves foráneas hay que activarlas por conexión.

Código de resultado
SQLITE_CONSTRAINT_FOREIGNKEY
Nombre
787
Categoría
Códigos de resultado extendidos
Mensaje de error
FOREIGN KEY constraint failed

Qué significa

SQLITE_CONSTRAINT_FOREIGNKEY (787) significa que falló una comprobación de clave foránea. SQLite solo aplica las claves foráneas en conexiones que ejecutan PRAGMA foreign_keys = ON; viene desactivado por compatibilidad con versiones anteriores, y por eso la misma inserción puede tener éxito en una herramienta y fallar en otra.

El mensaje no indica qué clave falló. PRAGMA foreign_key_check enumera cada fila que viola la regla.

Causas comunes

  • Insertar una fila hija cuyo id de padre no existe.
  • Eliminar o actualizar una fila padre que aún tiene hijos, sin ON DELETE CASCADE o SET NULL.
  • Cargar tablas en el orden incorrecto: hijos antes que padres.
  • Restricciones diferidas (DEFERRABLE INITIALLY DEFERRED) fallando en COMMIT.

Cómo solucionarlo

  1. Encuentra las filas que rompen una clave foránea.

    PRAGMA foreign_key_check;
    PRAGMA foreign_key_list(orders);
  2. Inserta los padres antes que los hijos, o elimina los hijos antes que los padres.

  3. Para cargas masivas, difiere la verificación hasta el final de la transacción.

    BEGIN;
    PRAGMA defer_foreign_keys = ON;
    -- load tables in any order
    COMMIT;
  4. Si eliminar un padre debería eliminar a sus hijos, declara la acción en la clave foránea.

    CREATE TABLE orders (
        id          INTEGER PRIMARY KEY,
        customer_id INTEGER NOT NULL REFERENCES customers(id) ON DELETE CASCADE
    );

Reprodúcelo de forma segura

PRAGMA foreign_keys = ON;
CREATE TABLE p (id INTEGER PRIMARY KEY);
CREATE TABLE c (pid INTEGER REFERENCES p(id));
INSERT INTO c VALUES (1);  -- Runtime error: FOREIGN KEY constraint failed (19)

Preguntas

¿Por qué no se aplican las claves foráneas en mi base de datos SQLite?

La comprobación de claves foráneas se aplica por conexión y está desactivada por defecto. Cada conexión debe ejecutar PRAGMA foreign_keys = ON, y no se puede cambiar dentro de una transacción.

Errores relacionados

Más errores de códigos de resultado extendidos

El código y el texto del mensaje son de Documentación de los códigos de resultado y de error de SQLite. Explora la lista completa de Lista de errores de SQLite o buscar cada error de base de datos.

// menos errores, correcciones más rápidas

Trabajar con SQLite en SQLly

Un cliente SQL nativo para macOS, Windows y Linux con IntelliSense que conoce el esquema, protecciones para las instrucciones de riesgo y mensajes de error claros, para SQLite y las demás bases de datos que uses.