Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(mcp): add early detection for multi-instance stdio contention (#611)

Matt Van Horne56e245e1bc9
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 5764fed1e..11f20037c 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -214,6 +214,12 @@ class OpenVikingService:
logger.debug("Already initialized")
return
+ # Acquire advisory lock on data directory to prevent multi-process
+ # contention (see https://github.com/volcengine/OpenViking/issues/473).
+ from openviking.utils.process_lock import acquire_data_dir_lock
+
+ acquire_data_dir_lock(self._config.storage.workspace)
+
if self._vikingdb_manager is None:
self._init_storage(
self._config.storage,
diff --git a/openviking/utils/process_lock.py b/openviking/utils/process_lock.py
new file mode 100644
index 000000000..854f624f7
--- /dev/null
+++ b/openviking/utils/process_lock.py
@@ -0,0 +1,102 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""PID-based advisory lock for data directory exclusivity.
+
+Prevents multiple OpenViking processes from contending for the same data
+directory, which causes silent failures in AGFS and VectorDB.
+"""
+
+import atexit
+import os
+import signal
+
+from openviking_cli.utils import get_logger
+
+logger = get_logger(__name__)
+
+LOCK_FILENAME = ".openviking.pid"
+
+
+class DataDirectoryLocked(RuntimeError):
+ """Raised when another OpenViking process holds the data directory lock."""
+
+
+def _read_pid_file(lock_path: str) -> int:
+ """Read PID from lock file. Returns 0 if unreadable."""
+ try:
+ with open(lock_path) as f:
+ return int(f.read().strip())
+ except (OSError, ValueError):
+ return 0
+
+
+def _is_pid_alive(pid: int) -> bool:
+ """Check whether a process with the given PID is still running."""
+ if pid <= 0:
+ return False
+ try:
+ os.kill(pid, 0)
+ return True
+ except ProcessLookupError:
+ return False
+ except PermissionError:
+ # Process exists but we can't signal it.
+ return True
+
+
+def acquire_data_dir_lock(data_dir: str) -> str:
+ """Acquire an advisory PID lock on *data_dir*.
+
+ Returns the path to the lock file on success.
+
+ Raises ``DataDirectoryLocked`` if another live process already holds the
+ lock, with a message that explains the situation and suggests HTTP mode.
+ """
+ lock_path = os.path.join(data_dir, LOCK_FILENAME)
+ my_pid = os.getpid()
+
+ existing_pid = _read_pid_file(lock_path)
+ if existing_pid and existing_pid != my_pid and _is_pid_alive(existing_pid):
+ raise DataDirectoryLocked(
+ f"Another OpenViking process (PID {existing_pid}) is already using "
+ f"the data directory '{data_dir}'. Running multiple OpenViking "
+ f"instances on the same data directory causes silent storage "
+ f"contention and data corruption.\n\n"
+ f"To fix this, use one of these approaches:\n"
+ f" 1. Use HTTP mode: start a single openviking-server and connect "
+ f"via --transport http (recommended for multi-session hosts)\n"
+ f" 2. Use separate data directories for each instance\n"
+ f" 3. Stop the other process (PID {existing_pid}) first"
+ )
+
+ # Write our PID (overwrites stale lock from a dead process).
+ try:
+ os.makedirs(data_dir, exist_ok=True)
+ with open(lock_path, "w") as f:
+ f.write(str(my_pid))
+ except OSError as exc:
+ logger.warning("Could not write PID lock %s: %s", lock_path, exc)
+ return lock_path
+
+ # Schedule cleanup on exit.
+ def _cleanup(*_args: object) -> None:
+ try:
+ if os.path.isfile(lock_path):
+ stored = _read_pid_file(lock_path)
+ if stored == my_pid:
+ os.remove(lock_path)
+ except OSError:
+ pass
+
+ atexit.register(_cleanup)
+ # Also try to clean up on SIGTERM (graceful shutdown).
+ try:
+ signal.signal(
+ signal.SIGTERM, lambda sig, frame: (_cleanup(), signal.default_int_handler(sig, frame))
+ )
+ except (OSError, ValueError):
+ # signal.signal() can fail in non-main threads.
+ pass
+
+ logger.debug("Acquired data directory lock: %s (PID %d)", lock_path, my_pid)
+ return lock_path
diff --git a/tests/misc/test_process_lock.py b/tests/misc/test_process_lock.py
new file mode 100644
index 000000000..458465931
--- /dev/null
+++ b/tests/misc/test_process_lock.py
@@ -0,0 +1,61 @@
+"""Tests for PID-based advisory lock on data directories."""
+
+import os
+import tempfile
+
+from openviking.utils.process_lock import (
+ LOCK_FILENAME,
+ DataDirectoryLocked,
+ acquire_data_dir_lock,
+)
+
+
+class TestProcessLock:
+ def test_acquires_lock_on_empty_dir(self):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ lock_path = acquire_data_dir_lock(tmpdir)
+ assert os.path.isfile(lock_path)
+ with open(lock_path) as f:
+ assert int(f.read().strip()) == os.getpid()
+
+ def test_same_pid_can_reacquire(self):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ acquire_data_dir_lock(tmpdir)
+ # Should not raise when same process re-acquires.
+ acquire_data_dir_lock(tmpdir)
+
+ def test_stale_lock_is_replaced(self):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ lock_path = os.path.join(tmpdir, LOCK_FILENAME)
+ # Write a PID that does not exist (very high number).
+ with open(lock_path, "w") as f:
+ f.write("999999999")
+ # Should succeed because the PID is dead.
+ acquire_data_dir_lock(tmpdir)
+ with open(lock_path) as f:
+ assert int(f.read().strip()) == os.getpid()
+
+ def test_live_pid_blocks_acquisition(self):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ lock_path = os.path.join(tmpdir, LOCK_FILENAME)
+ # PID 1 (init/launchd) is always alive.
+ with open(lock_path, "w") as f:
+ f.write("1")
+ try:
+ acquire_data_dir_lock(tmpdir)
+ raise AssertionError("Should have raised DataDirectoryLocked")
+ except DataDirectoryLocked as exc:
+ assert "PID 1" in str(exc)
+ assert "HTTP mode" in str(exc)
+
+ def test_error_message_includes_remediation(self):
+ with tempfile.TemporaryDirectory() as tmpdir:
+ lock_path = os.path.join(tmpdir, LOCK_FILENAME)
+ with open(lock_path, "w") as f:
+ f.write("1")
+ try:
+ acquire_data_dir_lock(tmpdir)
+ except DataDirectoryLocked as exc:
+ msg = str(exc)
+ assert "openviking-server" in msg
+ assert "separate data directories" in msg