Abort: cannot lock repository when using hg serve on low‑traffic deployments

Resolution

For a low-traffic Mercurial repository (fewer than one commit per day), the most effective way to eliminate abort: cannot lock repository errors and minimize resource overhead is to restrict the server to a single worker thread.

hg serve --workers 1 --timeout 30

Lock Contention and Worker Count

The cannot lock repository error occurs when multiple worker threads attempt to acquire the exclusive lock located at .hg/store/lock simultaneously. While hg serve is primarily used for read-only access, the underlying store mechanisms may still trigger lock checks depending on the filesystem and Mercurial version.

By setting --workers 1, you ensure that only one request is processed at a time. This removes concurrency-driven contention entirely, as there is no second thread to compete for the lock. In low-traffic scenarios, the trade-off—queuing requests if one takes an unusually long time—is negligible compared to the benefit of stability and reduced I/O spikes.

The Role of Request Timeouts

The --timeout setting does not prevent the initial lock contention, but it manages the lifecycle of the worker thread. A lower timeout (e.g., 30 seconds) prevents stale or hung connections from holding onto resources or keeping a worker occupied longer than necessary. For low-traffic deployments, a conservative timeout prevents stalled threads from impacting the available worker pool; with --workers 1, its primary benefit is freeing the single slot for the next legitimate request.

Lockfile Disabling and Read-Only Mode

There is no official Mercurial configuration to globally disable the .hg/store/lock file. Attempting to manually bypass the lock mechanism via filesystem permissions or hacks is strongly discouraged, as it can lead to repository corruption if any write operation (such as an automated update or administrative task) occurs while the server is active.

Verification Steps

To verify this configuration, execute the following:

1. Check your Mercurial version with hg version to confirm flag compatibility.
2. Start the server: hg serve --workers 1 --timeout 30
3. Simulate simultaneous requests using a tool like curl or ab (Apache Benchmark) to ensure requests are queued rather than failing with a lock error.
4. Monitor the .hg/store/lock file during these requests to confirm the absence of contention.

Diagnostic Detail Needed: Are you hosting the repository on a network filesystem (e.g., NFS)? Lock behavior varies significantly between local filesystems and network mounts, which may require additional mount-level tuning.