Comfy-Org/ComfyUI · error · RuntimeError

Could not acquire lock on database '{db_path}'. Another Comf

Error message

Could not acquire lock on database '{db_path}'. Another ComfyUI process may already be using it. Use --database-url to specify a separate database file.

What it means

ComfyUI guards its SQLite database with an OS-level file lock (db_path + '.lock') acquired with zero timeout. If another process already holds the lock, init fails immediately with this RuntimeError instead of silently corrupting the database. The lock is released automatically by the OS when the holding process exits, so a genuinely stale lock is rare.

Source

Thrown at app/database/db.py:87

    else:
        raise ValueError(f"Unsupported database URL '{url}'.")


_db_lock = None

def _acquire_file_lock(db_path):
    """Acquire an OS-level file lock to prevent multi-process access.

    Uses filelock for cross-platform support (macOS, Linux, Windows).
    The OS automatically releases the lock when the process exits, even on crashes.
    """
    global _db_lock
    lock_path = db_path + ".lock"
    _db_lock = FileLock(lock_path)
    try:
        _db_lock.acquire(timeout=0)
    except Timeout:
        raise RuntimeError(
            f"Could not acquire lock on database '{db_path}'. "
            "Another ComfyUI process may already be using it. "
            "Use --database-url to specify a separate database file."
        )


def _is_memory_db(db_url):
    """Check if the database URL refers to an in-memory SQLite database."""
    return db_url in ("sqlite:///:memory:", "sqlite://")


def init_db():
    db_url = args.database_url
    logging.debug(f"Database URL: {db_url}")

    if _is_memory_db(db_url):
        _init_memory_db(db_url)
    else:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Find and stop the other ComfyUI process (ps aux | grep -i comfy, or check the container) and restart.
Start the second instance with its own database: pass --database-url sqlite:///path/to/other.db.
If no process is running, verify none is holding the lock (lsof <db_path>.lock) and delete the orphaned .lock file.
For scripted/CI usage, point --database-url at a temp file or sqlite:///:memory:.

Example fix

# before (second instance, same db)
python main.py

# after
python main.py --database-url sqlite:////tmp/comfyui-second.db

Defensive patterns

Strategy: validation

Validate before calling

from filelock import FileLock, Timeout
lock = FileLock(db_path + ".lock")
try:
    lock.acquire(timeout=0)
    lock.release()  # probe only: another process holds it if Timeout raised
    ok = True
except Timeout:
    ok = False
print("db free:", ok)

Try / catch

from app.database.db import init_db
try:
    init_db()
except RuntimeError as e:
    if "Could not acquire lock" in str(e):
        sys.exit("Another ComfyUI instance is running; pass --database-url for a separate db.")
    raise

Prevention

Always pass an explicit --database-url when running multiple ComfyUI instances.
Use sqlite:///:memory: or a temp file for tests and scripts.
Check for running instances before starting a new one.

When it happens

Trigger: Starting a second ComfyUI instance pointing at the same database file (default user directory) while the first is still running; running ComfyUI and a separate script/tool that calls init_db on the same path; a hung or backgrounded ComfyUI process that never exited.

Common situations: Launching two ComfyUI instances to 'parallelize' generation; a systemd/docker container plus a manual run sharing a mounted user directory; a previous crash whose process is still zombie-locked; running tests against the production database while the server is up.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/54fb26a4253ffa70. Report an issue: GitHub.