Read-only: unable to obtain shared lock

Category: Read-OnlyVersions: 3.7.0+

🔴 Production Risk Error

Medium — reads will fail on constrained mounts.

What this means

SQLITE_READONLY_CANTLOCK (520) is returned when a read-only connection cannot acquire the shared lock needed to start a read transaction, because the shared-lock byte cannot be written (the file is read-only).

Why it happens

1Database file is on a read-only filesystem that does not support the lock byte mechanism.
2Shared-cache mode on a read-only file.

How to reproduce

Read-only filesystem mount, certain Docker or Kubernetes volume configurations.

trigger — this will ERROR

# Mount a database read-only where lock bytes cannot be written
import sqlite3
conn = sqlite3.connect('file:/ro/my.db?mode=ro', uri=True)
conn.execute('SELECT 1')  # May raise SQLITE_READONLY_CANTLOCK

sqlite3.OperationalError: unable to open database file

Fix 1

Why this works

Use immutable mode for truly read-only databases: file:my.db?immutable=1

Fix 2

Why this works

Mount with nolock option if the filesystem supports it, or use a local copy.

Sources

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

🔧 Source ref: sqlite3.h — SQLITE_READONLY_CANTLOCK = 520

📖 Further reading: SQLite URI filenames

Confidence assessment

⚠️ MEDIUM confidence

Stable.