Read-only: unable to initialise shared memory

Category: Read-OnlyVersions: 3.16.0+

🔴 Production Risk Error

Medium — read-only access fails until -shm is initialised.

What this means

SQLITE_READONLY_CANTINIT (1288) is returned when a read-only connection is unable to initialise the WAL-mode shared memory (-shm file), because initialisation would require a write.

Why it happens

1WAL-mode database opened read-only where -shm file does not yet exist.
2First connection to a WAL database is read-only and cannot create -shm.

How to reproduce

Read-only open of a WAL-mode database when -shm initialisation is needed.

trigger — this will ERROR

import sqlite3
# Open WAL database read-only with no existing -shm:
conn = sqlite3.connect('file:wal.db?mode=ro', uri=True)
conn.execute('SELECT 1')  # may raise SQLITE_READONLY_CANTINIT

sqlite3.OperationalError: attempt to write a readonly database

Fix 1

Why this works

Open the database read-write at least once to create the -shm file, then switch to read-only.

Fix 2

Why this works

Use immutable=1 URI parameter to skip shm entirely: file:wal.db?immutable=1

Sources

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

🔧 Source ref: sqlite3.h — SQLITE_READONLY_CANTINIT = 1288

Confidence assessment

⚠️ MEDIUM confidence

Stable.