Lock File Handling During Install/Uninstall¶
This document describes how lock files (vayu.lock) are handled during installation and uninstallation across all platforms.
Overview¶
One engine runs per data directory. The engine takes an exclusive lock at startup and exits 1 with "Another instance of Vayu Engine is already running" when another engine holds it. What it locks differs by platform:
- Linux and macOS: a
flockon the data directory itself, plus one onvayu.lockinside it. The directory lock is the guard: aflocklives on an inode, so a lock on the file alone was released for every newcomer the moment something unlinked the file, and two engines then served one database (issue #2422). Deletingvayu.lockno longer lets a second engine in. The file is still locked so an engine from before this change, which locks only the file, and a current one keep each other out. A filesystem that cannot lock a directory (some network volumes answerENOTSUPorEINVAL) falls back to the file alone, and the engine logs a warning that the guard is weaker there. - Windows:
vayu.lockis opened with share mode 0 and byte-locked, so it cannot be deleted while the engine holds it.
Every platform releases the lock when the engine process ends, however it ends.
vayu.lock itself is the PID record the app reads (checkLockFile): it holds
the PID of the running engine process and is located at:
- Windows:
%APPDATA%\Vayu\vayu.lock - macOS:
~/Library/Application Support/Vayu/vayu.lock - Linux:
~/.config/Vayu/vayu.lock
The directory is app.getPath("userData"), which main.ts sets to
USER_DATA_DIR_NAME (app/electron/constants.ts) before anything opens a file
there. engineDataDirectory()
(app/electron/sidecar.ts) is the one place that resolves it; anything else
naming a directory is a copy that can drift.
Platform-Specific Handling¶
Windows (NSIS Installer)¶
Installation (installer.nsh):
- Checks if Vayu is running and prompts user to close it
- Kills any orphaned vayu-engine.exe processes
- Removes stale lock files during installation
- Not on an updated launch. "Restart to install" runs the installer with
--updated (not /S) while the app is still shutting down - the renderer's
save flush, then the engine's graceful exit. customInit does none of the
three there: no prompt, no taskkill, no lock Delete. electron-builder's
own running-app check waits for the app to exit and force-kills only after,
and a lock left behind is reclaimed by app startup (#1882)
Uninstallation (installer.nsh):
- Kills running Vayu and engine processes before uninstall
- "Keep my data" removes only the lock file; "Delete everything" removes the whole data directory, and logs a skip rather than deleting anything if that directory is not there
- Lock file path: $APPDATA\${APP_DATA_DIR}\vayu.lock
NSIS cannot read package.json, so the script defines APP_DATA_DIR once and
uses it everywhere rather than spelling a path.
app/electron/installer-nsh-paths.test.ts fails if that define drifts from the
name, if any path bypasses it, or if a path segment anywhere in the file -
comments included - is productName. It is the Windows counterpart to the
Script lint job's check over the shell scripts, which covers ~/.config/ and
cannot see a .nsh file.
Both macros also flip NSIS back to the user's shell context around those paths.
An all-users install leaves NSIS in the machine context, where $APPDATA is not
the roaming profile Electron writes userData to - so a correctly named path
would still miss the real directory in that install mode.
Until #1393 the script named productName for both, so "Delete everything"
ran RMDir /r over $APPDATA\Vayu and removed nothing the app owns - the same
wrong-directory defect the Linux hooks had, and worse, because here it was a
promise about the user's data rather than a no-op.
macOS (DMG)¶
Installation: - No install hooks (DMG doesn't support them) - Lock file cleanup handled automatically in app startup (see below)
Uninstallation: - User manually drags app to Trash - Lock file cleanup handled automatically in app startup on next launch
Linux (.deb Package)¶
Installation:
- No maintainer script of Vayu's. The package's postinst is the one
electron-builder generates; stale locks are reclaimed by app startup (see
below)
Uninstallation:
- app/installer/linux-prerm.sh, wired as fpm's --before-remove in
app/electron-builder.json, kills any running vayu-engine so dpkg does not
replace or remove the binary underneath a live process. It touches no path,
which is why running as root does not break it
- Lock file cleanup handled automatically in app startup
A postinst and a postrm hook used to clean the lock file here. They were
removed (#1356): both looked for $HOME/.config/vayu/vayu.lock, a directory the
app has never written, and dpkg runs maintainer scripts as root, so even the
right directory name would have resolved under /root rather than the
installing user's home. The recovery they attempted - read the PID, verify it
belongs to vayu-engine, remove the file if not - is what startup already does,
against a path it resolves rather than spells, and at every launch rather than
only at install time.
They also cost more than they looked. afterInstall and afterRemove are
passed to fpm as --after-install and --after-remove, which replace
electron-builder's generated maintainer scripts rather than running alongside
them, so every .deb built while those hooks existed shipped the lock cleanup
in place of the /usr/bin/vayu-client alternative, the chrome-sandbox mode
fix, the mime and desktop database updates and the AppArmor profile Ubuntu 24
requires. Removing them restores all of it. Anything a future hook needs to do
belongs in a script that keeps that generated content, not one that supersedes
it.
AppImage: - No install/uninstall hooks - Lock file cleanup handled automatically in app startup
Automatic Cleanup on App Startup¶
The Electron sidecar (app/electron/sidecar.ts) automatically handles stale lock files:
- Checks lock file before starting the engine
- Reads PID from lock file
- Verifies process is still running - cheap first, subprocess second: a
signal-0 probe answers a PID nothing holds, and only a live PID is worth a
tasklist/pscall to verify the name - Removes stale lock only when that is proven: the PID is dead, or the
name read back is not
vayu-engine - Keeps the lock of a live PID whose name could not be read (below)
- Waits for, then replaces, a live engine that never answers
/health(below) - Logs warnings for debugging
This ensures that: - Stale locks from crashes are cleaned up - Reinstalls work correctly - No manual intervention needed
A PID it cannot classify keeps its lock, and is never killed (issue
2422). The name check is a subprocess (ps -p <pid> -o comm=, or tasklist¶
on Windows), and it can fail to run: ps missing from a minimal container, a
tasklist that errors. engineProcessState answers unknown then, distinct
from not-engine, because a live PID whose name cannot be read may be the
engine. The sidecar treats it as live for the lock (it is not removed) and as
unverified for the kill (the name-verified kill refuses it, so a recycled PID
is never signalled). Startup stays bounded: the PID goes through the wait
below on the same health budget, the stop's grace period, then the spawn, and
the engine's own lock decides whether this session's engine can start. A PID
recycled by another program on such a system costs that wait once; the new
engine then writes its own PID over the file.
A live engine is replaced, never adopted (issue #2356). The lock file can
point at a PID that is alive and answering /health: an orphan from a crashed
session, two installed builds sharing a data directory, or an engine started by
hand on this data directory. Every write to file trust (an allowed folder, a
picked file) needs the grant secret the app passes the engine it spawns, and
that engine was given another launch's secret or none, so EngineSidecar stops
it (POST /shutdown, then the same PID kill the graceful path already falls
back to) and spawns its own on the same port. That also covers an engine built
for a different Vayu release (issue #1492).
Only an engine serving this data directory is stopped (issue #3328). An
engine answering /health on a candidate port is the app's when the dataDir
it reports matches the app's data directory (both resolved, no trailing
separator, case ignored on Windows only). One serving another directory - a
standalone vayu-engine for vayu-cli, a second app instance on another
profile - holds its port like any other program: never sent /shutdown, never
killed, and the next candidate is tried. An engine too old to report dataDir
is never the app's, with or without a live lock: the lock proves the app's
engine exists, not that this answering engine is it, so it is left alone and
its port counted held. After upgrading across that change, an orphan of the old
release must be quit by hand (the port-in-use error names it). A standalone
daemon is left alone only when its --data-dir differs from the app's, which
is <repo>/engine/data in a development build: a daemon run from engine/
with its defaults serves that same directory and is replaced, so give it its
own --data-dir.
A live lock PID that does not answer /health is waited for, then replaced
(issue #1905). Between "stale" and "healthy" there is a third case: the PID is
alive and is a Vayu engine, but nothing answers on the port. It is either still
starting - an orphan from a crashed session reads its database and runs
migrations before it listens - or hung. Spawning beside it loses the flock, and
reporting the port as held would blame another program for Vayu's own engine.
So EngineSidecar polls /health on the same ramped
budget a freshly spawned engine gets (ENGINE_HEALTH_POLL_BUDGET_MS). An
engine that answers in time as this data directory's is asked to shut down and
replaced like any other (above); an answer from an engine serving another
directory does not end the wait. One that does not is stopped by PID (the name-verified kill, so a
recycled PID is left alone), the port is given ENGINE_PORT_RELEASE_DELAY_MS
to clear, the replaced PID is logged, and this instance spawns its own. The
port-in-use error (EnginePortInUseError) is left for ports held when the lock
file names no live Vayu engine, or held by an engine serving another data
directory.
A live lock is looked for on every candidate port (issue #2118). The engine
may run on 9876 or a fallback (ENGINE_PORT_CANDIDATES), so with a live lock
PID every candidate is asked for /health before any free port is taken: an
orphan left on a fallback port is replaced there even after 9876 has come free,
and an engine serving another data directory on an earlier candidate does not
shadow it. When it answers on none, the wait above watches the first free
candidate (where a still-starting engine, not yet listening, would be), or the
first not held by another data directory's engine when none is free. When every
candidate is held by such engines, startup reports "Another Vayu engine is using
port 9876" without waiting.
The engine releases the lock after its database has closed (issue #2420).
run_daemon (engine/src/daemon.cpp) holds the lock in an InstanceLock
declared before the Database, so on the way out the database's destructor -
its close-time WAL checkpoint included - runs first and the lock goes last, on
an early exit and a thrown startup error as much as on a graceful shutdown. A
replacement that wins the lock therefore never meets its predecessor's
connection at its own startup probe. A graceful shutdown's final refresh of
<db>.bak (issue #2421) runs before the database closes, so the lock is held
through that copy too, and a replacement never starts against a backup still
being written. If something else still holds the
database when an engine starts (a sqlite3 shell left in a transaction, a sync
agent), the engine waits for it (10 s on each connection it opens), then exits 1 naming the database
and leaves every file as it was, rather than treating the held file as corrupt
(db-schema.md).
Because the lock is held before the database opens, the startup reconcile that
marks running and pending runs as failed only ever meets runs a dead engine
left behind; the lock is the whole ownership check, and run rows carry no owner.
Manual Cleanup¶
Quit Vayu first. A lock file left behind after that is only a stale PID record (the lock itself went with the engine process), and removing it is safe:
Windows:
macOS/Linux:
Removing it while an engine still runs frees nothing: on Windows the delete fails, and on Linux and macOS the engine keeps its lock on the data directory, so a second engine is still refused. To stop an engine that will not quit, end the process whose PID the file names.
Implementation Details¶
Windows Implementation¶
- Uses
tasklistandtaskkillcommands - NSIS macros:
customInit,customUnInit,customUnInstall - File:
app/installer/installer.nsh
Linux Maintainer Scripts¶
app/installer/linux-prerm.sh: pre-removal, kills a runningvayu-engine- It is the only one Vayu writes. The packaged
.debstill carries apostinstand apostrm, both generated by electron-builder: the/usr/bin/vayu-clientalternative, thechrome-sandboxmode, the mime and desktop databases and the AppArmor profile Ubuntu 24 needs.afterInstallandafterRemovereplace those generated scripts rather than adding to them, which is what made the two removed hooks worse than dead: every.debbuilt while they existed shipped their lock-file cleanup instead of that setup.
Electron Sidecar¶
- Function:
checkLockFile()- reads the lock file's PID and classifies it - Function:
engineProcessState()- cross-platform process check with process name verification, answeringengine,not-engineorunknown.process.kill(pid, 0)first on every platform (no subprocess, and the stale-lock case ends there), thentasklist/psto verify the name against PID reuse; a name check that cannot run answersunknown, which keeps the lock and is never killed - Method:
liveLockPid()- removes the lock only for anot-enginePID - Method:
identify()- whose engine answers/healthon a port:ours(itsdataDiris this app's),foreign(anotherdataDir, or none reported), ornone - Method:
replaceAnsweringEngine()- stops a healthy engine of oursstart()finds already on the port, so it can spawn its own - Method:
replaceLockedEngine()- settles a live lock PID: waits onpollWithinBudget()for ours to answer, then asks it to shut down if it answered or kills it if it stayed silent - Automatic cleanup in
start()method - File:
app/electron/sidecar.ts
Testing¶
To test lock file handling:
- Start Vayu - lock file should be created
- Kill engine process - lock file should remain
- Restart Vayu - stale lock should be detected and removed
- Reinstall - the first launch after it reclaims any lock left behind
- Delete the lock under a live engine (Linux and macOS) - with an engine
running, remove
vayu.lockand startvayu-engine --data-dir <same dir>: the second engine exits 1 with "already running" and the first is untouched.engine/tests/file_lock_test.cppasserts the same in-process
Troubleshooting¶
Issue: Lock file prevents engine from starting after crash
Solution: A crash releases the lock with the process, so the file left behind names a dead PID and the app cleans it up on startup. An engine that still refuses to start is refused by a live engine on the same data directory, not by the file: stop the PID it names (see Manual Cleanup above).
Issue: Multiple instances error after uninstall/reinstall
Solution: Startup reclaims a lock whose PID is dead or provably not vayu-engine, so launching the reinstalled app is the fix. A live engine that never answers /health is replaced automatically after the health budget; if the engine still refuses to start, the replacement kill failed - stop the PID in the lock file. Removing the lock file does not help while that engine lives.