Truncated .sync-index.json permanently kills sync init — written in place, and a parse error is never recovered
Back to board### OS
Windows 11 Pro 25H2 (build 26200.8875)
### Node.js version
v24.16.0
### AI client
Claude Code 2.1.220
### Plugin / MCP server version
v2.11.1 (plugin and MCP server both
### Steps to reproduce
**Environment**
| | |
|---|---|
| Plugin version | 2.11.1 (current `@latest`) |
| MCP server version | 2.11.1, launched as `npx -y @weppy/roblox-mcp@latest` (stdio) |
| AI client | Claude Code 2.1.220 |
| Model | Claude Opus 5 |
| OS | Windows 11 Pro 25H2 (build 26200.8875) |
| Node.js | v24.16.0 |
| Roblox Studio | 0.731.0.7310942 |
| Tier | PRO |
| Place | ordinary small place — ~4,200 instances, ~2.8 MB script source |
**Steps**
1. Use a sync-enabled place and let one full sync complete, so `<syncRoot>/.sync-index.json` exists.
2. Truncate that file so it ends **inside a string** — `fs.truncateSync(idx, size - 200)`, or kill
the process during the ~13 ms window in which the index is rewritten in place (evidence in
FIELD 4). In the original incident the file was simply *found* in this state after a reboot;
what interrupted the write is not recorded anywhere.
3. Make sure the MCP server process is **started fresh** afterwards. This step is essential —
see the negative result below.
4. Start sync from the plugin — or just let the plugin auto-start it on connect, which is what
happened here, with no user interaction at all.
5. Sync init fails instantly and stays failed: plugin restarts, Studio restarts and PC restarts
do not help.
**Negative result — do not skip step 3.** On a *warm* server that had already completed a full
sync for the place, the same manipulation produces **no failure at all**: we stopped the sync,
replaced the index with a byte-identical copy truncated inside a string (5,774,498 B instead of
5,774,793 B) and started sync again — it ran through normally and overwrote the truncated file
with a valid index at completion. Same process, unchanged `serverInstanceId`, the very code path
that had failed hours earlier while cold. The reason is visible in the code (FIELD 4): the index
is only read when the process holds no context for that place. A reproduction attempt on a warm
server therefore silently "fails to fail".
### Expected behavior
1. A damaged local cache file should not be able to kill sync init permanently. A corrupt
`.sync-index.json` should take the same route a missing one already takes: log it, move it
aside, rebuild the index via full sync. `ENOENT` is handled exactly that way today — which is
precisely why deleting the file by hand is the working fix.
2. The index should be written crash-safely — through the same `atomicWrite()` (tmp + rename)
that this writer already uses for its other files, so an interrupted write cannot destroy the
only copy.
3. The error surfaced to the user should name the file it is talking about.
### Actual behavior
- ❌ The number in the error message is exactly the **file size** of `<syncRoot>/.sync-index.json`
(22,544,384 B). The parser ran out of input at the end of the file.
- ❌ The file ends mid-record, with no closing quote. Only the **last 225 bytes** are missing:
trimming back to the last complete entry and closing the braces yields valid JSON with all
7 top-level keys. It is a pure write abort, not content corruption.
- ❌ 22,544,384 = **344 × 64 KiB exactly** — the write stopped on a buffer boundary.
- ✅ It is truncation, **not** an encoding problem: V8 reports `Unterminated string` only when the
input ends inside a string; a raw control character or an unescaped quote produce different
messages (table in FIELD 4).
- ✅ Not disk or AV damage: files written by the same sync flush seconds earlier are valid JSON.
- 🔴 **The index is rewritten in place, not atomically** — measured with `fs.watch` over a full
sync: the file is truncated to 0 B at its final path and refilled 13 ms later, with no
`.tmp.*` involved at any point. For those 13 ms no complete copy exists anywhere on disk, and
the window scales with the file, which had grown to 22.5 MB when this went wrong.
- ✅ The same writer *does* use the atomic path for its neighbours — `sourcemap.json` is written
as `sourcemap.json.tmp.<hex>` and then renamed.
- 🔁 The read path rethrows: the sync-format version probe `JSON.parse`s the index and only
handles `ENOENT`; everything else propagates up through `handleInitStart` to `handleSyncInit`
and is returned to the plugin verbatim.
- ⚠️ The damage is **latent**: a corrupt index sits unnoticed until the next cold start, because
a running process never re-reads it.
**Suggested fix**
1. Persist the index through the existing `atomicWrite()` (tmp + `rename`, ideally `fsync` before
the rename). Removes the whole failure class.
2. On a parse or validation failure of `.sync-index.json`: log a warning, move the file aside
(`.sync-index.json.corrupt-<ts>`) and rebuild — exactly like the `ENOENT` path already does.
Never let it kill sync init.
3. Name the file in the error message. `handleSyncInit: Unterminated string in JSON at position
22544384` gives the user nothing to act on; they cannot know it refers to a local cache file.
Error as shown by the plugin:
```text
Failed to send sync start: handleSyncInit: Unterminated string in JSON
at position 22544384 (line 332670 column 53)
```
The file it is talking about, and its tail:
```text
<syncRoot>\.sync-index.json 22,544,384 B ( = 344 x 64 KiB exactly)
"process:<uuid>" + one literal NUL byte + "<sessionDebugId>": {
"scope": "process:<uuid>",
"sessionDebugId": "<sessionDebugId>",
"instancePath": "game.ServerStorage.SomeFold <-- EOF, no closing quote
```
Reproducing the message locally from that exact file:
```js
JSON.parse(fs.readFileSync('.sync-index.json', 'utf8'))
// -> Unterminated string in JSON at position 22544384 (line 332670 column 53)
```
Why that message means truncation and not bad encoding (verified on this Node build):
| Defect | V8 message |
|---|---|
| input ends inside a string | `Unterminated string in JSON at position N` ← our case, N = input length |
| raw control char in string | `Bad control character in string literal in JSON at position N` |
| unescaped `"` | `Expected ',' or '}' after property value in JSON at position N` |
Neighbouring files of the same sync flush — not disk/AV damage:
```text
sourcemap.json mtime 09:57:45.422Z valid
.sync-index.json mtime 09:58:04.418Z TRUNCATED
.sync-meta.json mtime 09:04:44.913Z valid
```
`fs.watch` on `<syncRoot>` — how the index is written, versus how its neighbour is written:
```text
# sourcemap.json, during normal syncing: tmp + rename (atomic)
11:50:29.708 rename sourcemap.json.tmp.9a9273ba 664,039 B
11:50:29.709 rename sourcemap.json 664,039 B
# .sync-index.json, at full-sync completion: truncate + refill at the final path
12:57:12.440 change .sync-index.json 0 B
12:57:12.453 change .sync-index.json 7,971,140 B
```
The index is not written per change and not on sync stop either (separate 60 s watches recorded
no event for both), only at full-sync completion.
Read path and call chain, from `dist/index.js` (2.11.1, minified):
```js
async function Upe(t){ // sync-format version probe
try{
let e = JSON.parse(await gq.readFile(t,"utf8"));
...
} catch(e){
if (e.code === "ENOENT") return null; // missing file -> handled, rebuild
throw e; // corrupt file -> propagates
}
}
handleSyncInit() -> handleInitStart() -> getOrCreatePlaceContext(placeId, placeName)
async getOrCreatePlaceContext(e,n){
let i = this.places.get(e);
...
if (!i) { // <- ONLY when this process holds no context for the place
let r = await this.config.resolvePlaceRoot(e,n),
o = await cx(r); // <- cx() -> Upe() -> JSON.parse(.sync-index.json) -> throws
...
}
}
```
That `if (!i)` guard is the whole cold/warm difference described in FIELD 1.
Reverse reproduction, with the expected message computed **before** running the test: we truncated
the current index (5,788,945 B) and restarted the MCP server (pid and `serverInstanceId` both
changed, uptime 26 s). The plugin auto-started sync on connect and produced:
```text
predicted: handleSyncInit: Unterminated string in JSON at position 5788945 (line 101530 column 46)
observed : handleSyncInit: Unterminated string in JSON at position 5788945 (line 101530 column 46)
```
Position, line and column all match. Restoring the backed-up index made sync healthy again:
`state: syncing`, 4,193 instances / 146 scripts, `lastFullSync` set, `applyModes` back to `auto`.
### Notes (optional context) — related findings from the same session
**The index is never pruned.** The corrupt index held 27,762 `explorer\…` entries while only
~4,300 files existed on disk. A freshly rebuilt index for the same place holds exactly as many
entries as there are files:
| | corrupt index | rebuilt index |
|---|---|---|
| size | 22,544,384 B | 5,774,793 B |
| `files` entries | 27,762 | 4,309 |
| files present in `explorer/` | 4,309 | 4,309 |
~23,450 entries pointed at files that no longer existed (they had been deleted on disk outside the
sync, and the index never noticed).
**`sessionDebugMappings` gains a full extra copy per Studio session.** Restarting the MCP server
(new plugin process token) and running one full sync added a second complete set to the index of
an otherwise unchanged place: `sessionDebugMappings` 4,193 → 8,386 (= 2 × instance count), index
size 5,789,240 → 7,971,140 B (+2.18 MB), distinct `"scope": "process:<uuid>"` keys 1 → 2. The two
scope keys are exactly the plugin `processToken`s of the two sessions; the older one is not
dropped. Together with the stale file entries, this is how the index reached 22.5 MB — and a
bigger index means a longer non-atomic write, i.e. a wider crash window.
**The failure is recorded nowhere on disk.** After deliberately reproducing it we searched the
daily plugin log, `observability/tools/history/*.jsonl`,
`observability/changelog/sessions/*.jsonl` and `observability/sync/changes.log`: **no hit** for
`handleSyncInit`, `Unterminated` or the position number in any of them. The failure exists only as
a toast in the plugin UI, which is also why we cannot say what interrupted the original write.
*Side observation, cause unknown:* after the MCP server restart the human-readable logs
(`observability/logs/current.log` and `plugin-<date>.log`) recorded the connect handshake and then
stopped entirely — no entries for ~65 minutes of tool calls, a sync stop and a full sync, with the
file mtime confirming nothing was written, while the other observability streams kept recording
normally. An earlier server restart the same day did not have this effect.
**Observability files inside the sync root are unbounded.**
`<syncRoot>/observability/changelog/sessions/*.jsonl` totalled **972 MB**, with single session
files of 205 MB / 197 MB / 107 MB, inside the directory users are told to treat as their project
folder (and, in our case, version-control it).
**Artifacts** — preserved and available privately on request; the truncated index contains the
full instance-path listing of a private, unreleased project, so it is not attached here:
the original `.sync-index.json` (22,544,384 B), the Node scripts used above (error-shape
discrimination, exact repro, trim-and-reparse proof, the `fs.watch` recorders, and the cold-start
test case builder that computed the predicted message in advance), and the raw watch transcripts.