{"record":{"id":"54fb26a4253ffa70","repo":"Comfy-Org/ComfyUI","slug":"could-not-acquire-lock-on-database-db-path-an","errorCode":null,"errorMessage":"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.","messagePattern":"Could not acquire lock on database '(.+?)'\\. Another ComfyUI process may already be using it\\. Use --database-url to specify a separate database file\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"app/database/db.py","lineNumber":87,"sourceCode":"    else:\n        raise ValueError(f\"Unsupported database URL '{url}'.\")\n\n\n_db_lock = None\n\ndef _acquire_file_lock(db_path):\n    \"\"\"Acquire an OS-level file lock to prevent multi-process access.\n\n    Uses filelock for cross-platform support (macOS, Linux, Windows).\n    The OS automatically releases the lock when the process exits, even on crashes.\n    \"\"\"\n    global _db_lock\n    lock_path = db_path + \".lock\"\n    _db_lock = FileLock(lock_path)\n    try:\n        _db_lock.acquire(timeout=0)\n    except Timeout:\n        raise RuntimeError(\n            f\"Could not acquire lock on database '{db_path}'. \"\n            \"Another ComfyUI process may already be using it. \"\n            \"Use --database-url to specify a separate database file.\"\n        )\n\n\ndef _is_memory_db(db_url):\n    \"\"\"Check if the database URL refers to an in-memory SQLite database.\"\"\"\n    return db_url in (\"sqlite:///:memory:\", \"sqlite://\")\n\n\ndef init_db():\n    db_url = args.database_url\n    logging.debug(f\"Database URL: {db_url}\")\n\n    if _is_memory_db(db_url):\n        _init_memory_db(db_url)\n    else:","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/app/database/db.py#L69-L105","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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:."],"exampleFix":"# before (second instance, same db)\npython main.py\n\n# after\npython main.py --database-url sqlite:////tmp/comfyui-second.db","handlingStrategy":"validation","validationCode":"from filelock import FileLock, Timeout\nlock = FileLock(db_path + \".lock\")\ntry:\n    lock.acquire(timeout=0)\n    lock.release()  # probe only: another process holds it if Timeout raised\n    ok = True\nexcept Timeout:\n    ok = False\nprint(\"db free:\", ok)","typeGuard":null,"tryCatchPattern":"from app.database.db import init_db\ntry:\n    init_db()\nexcept RuntimeError as e:\n    if \"Could not acquire lock\" in str(e):\n        sys.exit(\"Another ComfyUI instance is running; pass --database-url for a separate db.\")\n    raise","preventionTips":["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."],"tags":["database","sqlite","concurrency","startup"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}