SQLITE_NOTFOUNDERRORTier 2 — Caution⚠️ MEDIUM confidence

Unknown opcode or table/row not found

Category: Not FoundVersions: 3.0+

🔴 Production Risk Error

Low — mostly internal to extension code.

What this means

SQLITE_NOTFOUND (12) is used internally by SQLite and by virtual table implementations. In user-facing contexts it appears when sqlite3_vtab_on_conflict() is called outside a conflict handler, or when a requested table or element is not found by an extension.

Why it happens

1Virtual table xUpdate method could not locate a row.
2sqlite3_vtab_on_conflict() called outside of an ON CONFLICT handler.
3Extension or custom VFS reporting a missing resource.

How to reproduce

Virtual table implementations and some SQLite C extension APIs.

trigger — this will ERROR

-- SQLITE_NOTFOUND is rarely exposed to SQL users directly
-- Typically seen in C extension code:
-- if (sqlite3_vtab_on_conflict(db) == SQLITE_NOTFOUND) { ... }

Surfaced as OperationalError in drivers when a virtual table cannot locate a row.

Fix 1

Why this works

Check that the virtual table's xBestIndex and xFilter implementations are consistent.

Fix 2

Why this works

Ensure sqlite3_vtab_on_conflict() is only called from within a conflict handler.

Sources

📚 Official docs: https://www.sqlite.org/rescode.html#notfound

🔧 Source ref: sqlite3.h — SQLITE_NOTFOUND = 12

📖 Further reading: SQLite virtual table API

Confidence assessment

⚠️ MEDIUM confidence

Stable.