Stale .sync.lock after hard kill blocks future syncs

[kennethwolters]

If the ob process is hard-killed (SIGKILL, crash), a stale lock directory remains at <vault>/.obsidian/.sync.lock. Subsequent ob sync calls fail with "Another sync instance is already running" even though no instance is running. The lock does not self-expire.

Workaround

rmdir <vault>/.obsidian/.sync.lock

Running under systemd handles normal stop/restart (SIGTERM triggers clean shutdown which releases the lock). But unclean deaths still leave a stale lock.

Environment

• OS: Linux (Ubuntu-based)
• Node: 24.14.0
• obsidian-headless: 0.0.3 (npm)

[pcontezini]

Same thing here, also, trying to sync 4 different repositories, and the lock seems to appear on all of them while syncing only one or two randomly, not sure why:

#!/bin/sh
VAULT_PATH="/home/xxxx/obsidian"
find $VAULT_PATH -type d -name ".sync.lock" -exec rm -rf {} +
for i in "$VAULT_PATH"/*/; do
echo starting ob sync in $i;
(cd $i ; ob sync --continuous 1>> ../basename $i.log 2>> ../basename $i.log &)
sleep 1
done

[wojas]

No need for a sigkill, it will randomly leave the lock behind on exit, perhaps due to a race condition.

[wojas]

Debug analysis with Codex:

Your suspicion is close, but the race is not "exit prevents removal." The stronger race is that shutdown can release the lock too early, not too late.

The shutdown path is:
cli.debug.js:3002 installs a signal handler that only calls a.stop().
cli.debug.js:1945 stop() is synchronous and immediately resolves this.resolveStop().
cli.debug.js:1931 sync() is waiting on that stop promise, so it returns as soon as stop() fires.
cli.debug.js:3011 the outer finally then calls o.release().

That means if a background requestSync() / _sync() is still in flight, the command can drop the lock before sync work has actually quiesced. That is a real shutdown race, but it would allow overlap with a new process, not leave a stale lock behind.

The stale-lock behavior is more likely caused by the lock implementation itself:
cli.debug.js:2708 release() only removes the directory if verify() passes.
cli.debug.js:2736 verify() requires exact mtimeMs equality.
cli.debug.js:2716 set() updates this.lockTime before touching the filesystem.
cli.debug.js:2720 touch() swallows all errors.

So if any utimesSync refresh fails, or the filesystem reports a slightly different timestamp than the one written, verify() fails and release() silently skips rmdirSync. That matches "stale lock files" much better than the exit path.

[lishid]

The lock should expire after 5 seconds. Its modified time is what is used to determine staleness, and it is refreshed faster to indicate use.

I've tweaked the exit code a bit to reduce possibility of a stale lock left behind, but if you do hardkill the script then it does not get a chance to delete it.

[johnorourke]

I'm seeing this error even on first run on a freshly set up empty directory, bringing a remote vault in:

rm -rf ~/.config/obsidian-headless/sync # clear settings and state
rm -rf vault-dir  # remove the vault
mkdir vault-dir

# ensure sync sees our vault directory as very old, otherwise it assumes it is authoritiative and deletes everything
touch -t 198001010000 vault-dir 

echo $MY_VAULT_KEY | ob sync-setup --vault 'My Vault Name' --path 'vault-dir' --device-name 'some-device'  # this works fine

cd vault-dir
ob sync

# randomly this gives the error - maybe 2 out of 5 times. 

Environment: obsidian-headless 0.0.6 on Ubuntu.

Next steps: am trying out a 5 second sleep before ob sync , referring to the 5 second timeout mentioned above.