How to fix SQLITE_IOERR_LOCK: Error obtaining file lock in SQLite

What this error means

The SQLITE_IOERR_LOCK error is an extended error code for SQLITE_IOERR (code 10) that specifically indicates a failure in SQLite's advisory file locking logic. SQLite relies on the operating system's file locking mechanisms to ensure data integrity and prevent corruption when multiple processes access the same database. This error typically manifests when SQLite attempts to obtain a PENDING lock on the database file but the underlying file system or operating system fails to grant it. The lock is essential for coordinating write access and ensuring ACID compliance. While SQLite's locking mechanism works reliably on local file systems, it can encounter problems on network file systems (like NFS, SMB/CIFS), certain cloud storage mounts, or file systems with broken or incomplete locking implementations. On some platforms, particularly macOS, this error can also indicate miscellaneous locking errors specific to specialized Virtual File Systems (VFSes) used by SQLite for different storage backends.

Typical symptoms

• Database operations fail with "SQLITE_IOERR_LOCK" or "disk I/O error" messages
• SQLite database creation works on local storage but fails on network-mounted drives
• Intermittent database access failures when multiple processes access the same database
• Error occurs specifically during write operations or transaction commits
• Database operations succeed when run with exclusive access but fail under concurrent load
• Lock-related errors appear more frequently on NFS, CIFS, or cloud-mounted storage

Common causes

1. Database file located on a network file system (NFS, SMB/CIFS) with broken or incomplete fcntl() file locking support
2. Multiple processes attempting concurrent write access without proper lock coordination
3. File system does not properly implement advisory file locking (common with some cloud storage mounts)
4. Stale lock files or corrupted lock state from previous crashed processes
5. Operating system or file system bugs affecting file locking primitives
6. Using SQLite on virtualized or containerized storage that doesn't fully support POSIX locking
7. Antivirus or file indexing software interfering with SQLite's lock files on Windows
8. Insufficient file permissions preventing lock file creation in the database directory
9. File system mounted with options that disable or modify locking behavior (e.g., nolock on NFS)

How to fix "SQLITE_IOERR_LOCK: Error obtaining file lock"

# Linux/macOS - check mount point and filesystem type
df -T /path/to/your/database.db

# Check if it's on a network mount
mount | grep -E "nfs|cifs|smb"

# Create a local directory for the database
mkdir -p /var/lib/myapp

# Move the database file
mv /mnt/network-share/app.db /var/lib/myapp/app.db

# Update your application configuration
# Update the database path in your code or config file
DATABASE_URL="file:/var/lib/myapp/app.db"

# Using SQLite CLI
sqlite3 /path/to/database.db "PRAGMA journal_mode=WAL;"

# Or in your application code

# Python example
import sqlite3
conn = sqlite3.connect('database.db')
conn.execute('PRAGMA journal_mode=WAL')
conn.commit()

// Node.js example with better-sqlite3
const Database = require('better-sqlite3');
const db = new Database('database.db');
db.pragma('journal_mode = WAL');

# Python - set a busy timeout
import sqlite3
conn = sqlite3.connect('database.db', timeout=10.0)  # Wait up to 10 seconds

// Node.js with better-sqlite3
const Database = require('better-sqlite3');
const db = new Database('database.db', { timeout: 5000 });
db.pragma('busy_timeout = 5000');

-- Or use PRAGMA in SQL
PRAGMA busy_timeout = 5000;

# Check current permissions
ls -la /path/to/database.db
ls -la /path/to/  # Directory permissions

# SQLite needs write access to the directory (for lock files)
chmod 755 /path/to/
chmod 644 /path/to/database.db

# Ensure correct ownership
chown youruser:yourgroup /path/to/database.db
chown youruser:yourgroup /path/to/

# Look for SQLite temporary files
ls -la /path/to/database.db*

# Remove WAL and shared memory files (database must be closed first!)
# WARNING: Only do this when NO processes are using the database
rm /path/to/database.db-shm
rm /path/to/database.db-wal

# Then try accessing the database again

# Migrate to PostgreSQL, MySQL, or other client-server database
# These are designed for network access and concurrent usage

# Run a service on a machine with local storage
# Applications connect to this service instead of direct file access
# The service manages the SQLite database with exclusive access

PRAGMA journal_mode=DELETE;

Advanced notes

Frequently asked questions

What does "SQLITE_IOERR_LOCK" mean?

The SQLITE_IOERR_LOCK error is an extended error code for SQLITE_IOERR (code 10) that specifically indicates a failure in SQLite's advisory file locking logic. SQLite relies on the operating system's file locking mechanisms to ensure data integrity and prevent corruption when multiple processes access the same database. This error typically manifests when SQLite attempts to obtain a PENDING lock on the database file but the underlying file system or operating system fails to grant it.

How do I fix "SQLITE_IOERR_LOCK"?

This I/O error occurs when SQLite cannot acquire the necessary file lock to access the database, typically due to file system limitations, network storage issues, or concurrent access conflicts.

What causes "SQLITE_IOERR_LOCK"?

Database file located on a network file system (NFS, SMB/CIFS) with broken or incomplete fcntl() file locking support Multiple processes attempting concurrent write access without proper lock coordination File system does not properly implement advisory file locking (common with some cloud storage mounts)

Is the "SQLITE_IOERR_LOCK" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• SQLITE_IOERR_READ: Disk I/O error during read

  How to fix 'SQLITE_IOERR_READ: Disk I/O error during read' in SQLite

  HIGH

• SQLITE_IOERR_FSYNC: Error during fsync()

  Error during fsync() system call

  CRITICAL

• SQLITE_IOERR_SHORT_READ: Read returned less data than requested

  How to fix 'SQLITE_IOERR_SHORT_READ: Read returned less data than requested' in SQLite

  HIGH

• SQLITE_INTERRUPT: Operation terminated by sqlite3_interrupt()

  How to fix "SQLITE_INTERRUPT: Operation terminated" in SQLite

  MEDIUM

• SQLITE_CORRUPT: The database disk image is malformed

  How to fix "SQLITE_CORRUPT: The database disk image is malformed" in SQLite

  CRITICAL

• SQLITE_READONLY: Attempt to write a readonly database

  How to fix "SQLITE_READONLY: Attempt to write a readonly database" in SQLite

  HIGH

Official resources & further reading

• 📚SQLite Official Documentation
• 📖
  Result and Error Codes - Official SQLite documentation(Official Docs)
• 📖
  File Locking And Concurrency In SQLite Version 3 - Official SQLite documentation(Official Docs)
• 🔗
  Understanding and Resolving the "SQLite Database is Locked" Error - Beekeeper Studio
• 🐙
  Cannot create sqlite database: SQLITE_IOERR_LOCK - GitHub Issue(GitHub)
• 🔗
  File Locking in SQLite: Ensuring Data Integrity - Runebook
• 🔗
  Troubleshooting Lock, Performance, and Integrity Issues in SQLite - Mindful Chase
• 🔗
  SQLite concurrent writes and "database is locked" errors - Ten Thousand Meters
• 🐙
  System.Data.SQLite.SQLiteException: database is locked on NFS - GitHub Issue(GitHub)