How to fix SQLITE_BUSY: The database file is locked in SQLite

What this error means

SQLITE_BUSY is a concurrency error that happens when SQLite attempts to write to a database file that is currently locked by another process or connection. SQLite uses file-based locking to ensure data integrity when multiple processes or threads access the same database. The error typically appears when: 1. **Multiple processes** try to write to the same database simultaneously 2. **A connection remains open** after a write operation, keeping the database locked 3. **File system issues** prevent proper lock acquisition or release 4. **Network file systems** (NFS, SMB) have delayed lock propagation SQLite supports three locking modes: UNLOCKED, SHARED, RESERVED, PENDING, and EXCLUSIVE. The SQLITE_BUSY error occurs when a connection tries to acquire a RESERVED or EXCLUSIVE lock while another connection holds a conflicting lock.

Typical symptoms

• Database operations fail with 'SQLITE_BUSY: The database file is locked'
• Errors occur intermittently, especially under high load
• Multiple applications or threads accessing the same SQLite database
• Operations work fine in isolation but fail when concurrent access increases
• Error appears during write operations (INSERT, UPDATE, DELETE) but reads may work
• Application works locally but fails when deployed with multiple instances

Common causes

1. Multiple processes or threads writing to the same database file simultaneously
2. Database connection not properly closed after write operations
3. Using SQLite over network file systems (NFS, SMB) with poor lock support
4. Long-running transactions that hold locks for extended periods
5. Application crashes leaving stale lock files (.db-wal, .db-shm, .db-journal)
6. Antivirus or backup software scanning database files and creating locks
7. File permissions preventing proper lock file creation
8. Using WAL (Write-Ahead Logging) mode without proper cleanup

How to fix "SQLITE_BUSY: The database file is locked"

# Find processes accessing the SQLite file
lsof /path/to/your/database.db

# Check for lock files
ls -la /path/to/your/database.db-*

# Use Handle or Process Explorer tools
# Or check for lock files
Get-ChildItem "C:path	oyourdatabase.db-*"

const db = require('better-sqlite3')('database.db');

// Use transactions for multiple operations
const insert = db.prepare('INSERT INTO users (name) VALUES (?)');
const select = db.prepare('SELECT * FROM users WHERE name = ?');

// Always close connection when done
process.on('exit', () => db.close());
process.on('SIGINT', () => db.close());

import sqlite3
import contextlib

@contextlib.contextmanager
def get_db_connection(db_path):
    conn = sqlite3.connect(db_path)
    try:
        yield conn
    finally:
        conn.close()

# Usage
with get_db_connection('database.db') as conn:
    cursor = conn.cursor()
    cursor.execute('INSERT INTO users (name) VALUES (?)', ('John',))
    conn.commit()

try (Connection conn = DriverManager.getConnection("jdbc:sqlite:database.db")) {
    try (PreparedStatement stmt = conn.prepareStatement("INSERT INTO users (name) VALUES (?)")) {
        stmt.setString(1, "John");
        stmt.executeUpdate();
    }
} // Connection automatically closed

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;

PRAGMA busy_timeout = 5000; -- Wait up to 5 seconds for locks

PRAGMA locking_mode = NORMAL; -- Default, allows shared locks

PRAGMA journal_mode = MEMORY; -- Faster but less durable
PRAGMA cache_size = -2000; -- 2MB cache

# Check for active connections
fuser /path/to/database.db

# If no output, it's safe to clean up
rm -f /path/to/database.db-wal
rm -f /path/to/database.db-shm
rm -f /path/to/database.db-journal

# Backup and recreate the database
sqlite3 database.db ".backup backup.db"
mv database.db database.db.corrupted
mv backup.db database.db

import fcntl
import os

class DatabaseLock:
    def __init__(self, db_path):
        self.lockfile = db_path + '.lock'
        self.fd = None

    def acquire(self):
        self.fd = open(self.lockfile, 'w')
        fcntl.flock(self.fd, fcntl.LOCK_EX)

    def release(self):
        if self.fd:
            fcntl.flock(self.fd, fcntl.LOCK_UN)
            self.fd.close()
            self.fd = None

# Usage
lock = DatabaseLock('database.db')
try:
    lock.acquire()
    # Perform database operations
finally:
    lock.release()

async function executeWithRetry(query, params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await db.run(query, params);
    } catch (error) {
      if (error.code === 'SQLITE_BUSY' && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 100 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}

// Example with better-sqlite3 pool
const Database = require('better-sqlite3');
const pool = [];

function getConnection() {
  if (pool.length > 0) {
    return pool.pop();
  }
  return new Database('database.db');
}

function releaseConnection(conn) {
  pool.push(conn);
}

Advanced notes

SELECT * FROM pragma_lock_status;

PRAGMA database_list;
PRAGMA wal_checkpoint(TRUNCATE);

export SQLITE_LOG=1
sqlite3 database.db

Frequently asked questions

What does "SQLITE_BUSY" mean?

SQLITE_BUSY is a concurrency error that happens when SQLite attempts to write to a database file that is currently locked by another process or connection. SQLite uses file-based locking to ensure data integrity when multiple processes or threads access the same database. The error typically appears when: 1.

How do I fix "SQLITE_BUSY"?

This error occurs when SQLite cannot access a database file because it's locked by another process or connection. Common causes include multiple applications accessing the same database, improper connection handling, or file system locking issues.

What causes "SQLITE_BUSY"?

Multiple processes or threads writing to the same database file simultaneously Database connection not properly closed after write operations Using SQLite over network file systems (NFS, SMB) with poor lock support

Is the "SQLITE_BUSY" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• SQLITE_CANTOPEN: Unable to open the database file

  Unable to open the database file

  HIGH

• SQLITE_BUSY_SNAPSHOT: Cannot promote read transaction to write transaction

  How to fix 'SQLITE_BUSY_SNAPSHOT: Cannot promote read transaction to write transaction' in SQLite

  MEDIUM

• SQLITE_CONSTRAINT: Abort due to constraint violation

  How to fix "SQLITE_CONSTRAINT: Abort due to constraint violation" in SQLite

  MEDIUM

• SQLITE_BUSY_RECOVERY: Another process is recovering a WAL mode database

  How to fix 'SQLITE_BUSY_RECOVERY: Another process is recovering a WAL mode database' 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
• 📖
  sqlite.org - rescode(Official Docs)
• 📖
  sqlite.org - lockingv3(Official Docs)
• 💬
  stackoverflow.com - sqlite+busy(Stack Overflow)