Failed to parse file: unexpected token when running biome write --write concurrently on the same file

Question

The goal is to determine whether Biome's --write operation provides an exact‑once guarantee when multiple processes invoke it simultaneously on the same file, taking into account its idempotent retry logic for transient I/O errors.

Biome retries a write after a transient failure using an idempotent approach, but the documentation does not specify any locking or serialization mechanism for concurrent invocations. A parse error aborts without attempting a write, leaving unclear whether overlapping successful writes could interleave, duplicate content, or corrupt the file.

Does Biome rely solely on filesystem atomic rename to prevent interleaving, or does it risk corrupting the file under concurrency? What observable behavior occurs when two processes retry a write after a simulated NFS latency? Is there any guarantee that the final file content reflects only one successful write?

Tasadduq Burney · Answer

Direct AnswerBiome does not provide an exactly‑once guarantee for concurrent biome format --write invocations on the same file. There is no cross‑process locking or serialization; each process independently reads, formats, and writes. The safety mechanism is an atomic rename (write‑to‑temporary‑file then rename), so the final file contains a complete formatted output from one process—not an interleaved byte stream.What Happens Under ConcurrencyLost updates / stale content: Two processes may read the same input, format it, and rename in either order. The last rename wins. If both processes compute identical output (same Biome version, same config, idempotent formatting), the result is deterministic.Parse errors: A process that reads the file while another’s write is mid‑flight (or reads a partially synced file over NFS) will encounter an “unexpected token” parse error and abort without writing. This is a symptom of the race, not corruption caused by Biome.Retries on transient I/O: Biome retries failed writes idempotently. Under simulated NFS latency you may see intermittent parse errors or stale‑read warnings, but the observable end state remains one complete formatted file.Confirmed Facts vs. Likely ExplanationConfirmed (from Biome’s general design)Likely / Version‑SensitiveWrite path uses temporary file + atomic rename on POSIX filesystems.Exact temp‑file naming, rename behavior, and retry conditions are not fully specified in public docs and may change between versions.Formatting is idempotent: formatting already‑formatted content yields the same output.Atomicity of rename on NFS or Windows depends on filesystem configuration and mount options.Parse failure aborts the write; no partial write is left behind.Concurrent invocations with different configs or Biome versions can produce flip‑flopping content that looks like corruption.Practical Verification StepsRun two concurrent biome format --write loops on the same file (e.g., 100 iterations in parallel shells) and verify the file parses cleanly and matches a single sequential format run.Add artificial latency (NFS mount with injected delay via tc or a FUSE wrapper) and log each process’s exit code and any “unexpected token” errors to confirm parse failures coincide with a concurrent writer.Compare file content hashes after concurrent runs: identical hashes to a sequential run confirm idempotent convergence; differing hashes indicate differing configs/versions rather than interleaving.Inspect Biome’s changelog and source for the current version’s file‑writing implementation before relying on atomicity assumptions.RecommendationTreat --write as safe for idempotent convergence but not for mutual exclusion. Serialize concurrent formatting yourself (CI job ordering, a lockfile, or running Biome once over a file set rather than per‑file parallel processes).One Missing Diagnostic DetailWhat Biome version and filesystem (local ext4, NFS version, Windows) are you using? The exact atomicity guarantees depend on these.

Failed to parse file: unexpected token when running biome write --write concurrently on the same file

1 answer

Direct Answer

What Happens Under Concurrency

Confirmed Facts vs. Likely Explanation

Practical Verification Steps

Recommendation

One Missing Diagnostic Detail

Your perspective belongs here.

0 question comments

Confirmed (from Biome’s general design)	Likely / Version‑Sensitive
Write path uses temporary file + atomic rename on POSIX filesystems.	Exact temp‑file naming, rename behavior, and retry conditions are not fully specified in public docs and may change between versions.
Formatting is idempotent: formatting already‑formatted content yields the same output.	Atomicity of rename on NFS or Windows depends on filesystem configuration and mount options.
Parse failure aborts the write; no partial write is left behind.	Concurrent invocations with different configs or Biome versions can produce flip‑flopping content that looks like corruption.