patch_vault_file silently corrupts content when targeting headings in nested sections

[grimlor]

Summary

patch_vault_file fails silently when the target heading exists inside a parent section. Instead of raising an error, it appends a new heading at the wrong level, corrupting the document structure.

Root Cause

The tool constructs heading targets using only the leaf heading name (e.g., "Section B"), but the underlying obsidian-local-rest-api passes this to markdown-patch, which requires fully-qualified hierarchical paths (e.g., "Parent Section\x1fSection B" using the unit separator \x1f as delimiter).

When the leaf-only lookup fails, markdown-patch falls through to createTargetIfMissing: true behavior and appends a new heading instead of raising PatchFailed. The caller receives no error signal.

Related Issues

• coddingtonbear/markdown-patch#7 — replace + createTargetIfMissing causes silent corruption instead of raising PatchFailed
• coddingtonbear/obsidian-local-rest-api#221 — MCP tool constructs leaf-only targets with no way for callers to provide qualified paths

Reproduction

1. Create a vault file with nested headings:

markdown

   # Parent Section
   ## Section B
   Original content

2. Call patch_vault_file targeting "Section B" with a replacement
3. Observe: a new ## Section B is appended at the end instead of replacing the existing one; no error is raised

Expected Behavior

Either:

• Accept fully-qualified heading paths (e.g., "Parent Section\x1fSection B") so callers can precisely target nested headings, or
• Raise a clear error when the target heading is ambiguous or not found at the top level

Workaround

Use create_vault_file for full rewrites. Heading-targeted patches via patch_vault_file are unreliable for any non-top-level heading.

[istefox]

For anyone still waiting on this — it's been fixed in the community fork at https://github.com/istefox/obsidian-mcp-connector (commit 046268b, released in v0.3.0).

You can install today via BRAT by pointing to istefox/obsidian-mcp-connector, or wait for the community-store entry pending at obsidianmd/obsidian-releases#11919.

Opening from the fork side to surface the pointer — feel free to close if you're satisfied, or keep open to track the upstream decision.

[folotp]

Confirming this bug on macOS 26.x with Obsidian 1.12.7, Local REST API 3.6.1, wrapper 0.2.27.

One point of scope rectification: in my repro the silent append-EOF fires even for root-level ## headings with no parent at all — not only for nested sections as the title suggests. Minimal fixture (all ASCII, no nesting):

## Section finale

Marker.

Call:

{
  "operation": "replace",
  "targetType": "heading",
  "target": "Section finale",
  "content": "REPLACED"
}

Result: "File patched successfully"; the original ## Section finale is untouched; REPLACED is appended at EOF under a derived # Section finale (H1) line.

This lines up with the root cause described in #71 and coddingtonbear/markdown-patch#7 / coddingtonbear/obsidian-local-rest-api#221: any leaf-only lookup that markdown-patch cannot resolve falls through to createTargetIfMissing. A root-level ## is not stored under a top-level heading key either (there is no # root), so the leaf-only target "Section finale" never matches. The failure mode is identical to the nested case — only the scope is wider than the title suggests.

Minor ancillary finding during the same test session: the same silent createTargetIfMissing fallback fires on targetType: "block" when the block ^id sits inside a markdown table cell (in that case without the spurious derived heading prefix, which matches what you would expect since markdown-patch resolves ^id blocks rather than heading paths). Blocks outside tables resolve correctly and patch in place, so PR #72's Create-Target-If-Missing: false lever would also make the block path safe for callers that want an explicit error on missing targets.

[istefox]

Hi @folotp — thanks for the rigorous follow-up. Two separate things in your comment, so I'll split them:

1. Root-level ## heading silent append-EOF

This is the exact failure mode addressed by the heading-path resolution fix shipped in the community fork's v0.3.0 (istefox/obsidian-mcp-connector, stable through v0.3.5). The partial-name lookup ("Section finale") now resolves to the full hierarchical path before the PATCH is issued, so leaf-only targets at any nesting depth — including true root-level — should work. If you test it on the fork and the root ## case still misfires, that's a repro I need; otherwise this half of your report can close.

2. targetType: "block" with ^id inside a markdown table cell

Confirmed this is a new gap, not covered by the fork's current pre-processing. The heading-path resolution only kicks in when targetType === "heading" (see packages/mcp-server/src/features/local-rest-api/index.ts:419-422); block targets pass straight through to LRA. When LRA's markdown-patch can't locate a block ^id inside a table cell, the createTargetIfMissing: true default (upstream-compat) produces the same silent EOF append you described.

Two mitigations, in order of effort:

• Caller-side workaround (ready today): set createTargetIfMissing: false on the call. It's wired as a parameter on both patch_active_file and patch_vault_file since 0.3.0 and will surface an explicit HTTP 404 / error instead of silently creating the target at EOF. If you can confirm this clears the ambiguity for your block-in-table case on the fork, we have a clean narrative: "createTargetIfMissing: false for hostile inputs, everything else is safe at 0.3.0+".
• Wrapper-side client validation (if the above isn't enough): pre-validate that the resolved block/heading target exists in the file body before issuing the PATCH. This is more invasive — we'd be duplicating part of markdown-patch's logic wrapper-side — so I'd prefer to confirm the simpler mitigation suffices first.

Would you mind trying the createTargetIfMissing: false variant on the fork and reporting back? Your methodical repros make this very tractable.

[istefox]

Heads-up @folotp — the block-in-table half of this issue is fixed in the community fork's v0.3.7, shipped today.

Behavior change: Create-Target-If-Missing now defaults per target type:

• heading → true (upstream 0.2.x compat, unchanged)
• frontmatter → true (unchanged)
• block → false (new default — an unresolvable ^id, including one inside a markdown table cell, now produces an explicit error instead of silently appending at EOF)

Callers who want permissive behavior on a block can still opt in explicitly with createTargetIfMissing: true.

6 regression tests pin the new per-target-type defaults in patchVaultFile.test.ts so a future refactor can't flip them silently.

If you can point your MCP client at the fork and re-run your block-in-table fixture, the expected shape is now:

• Before the fix: HTTP 200 + silent EOF append + compounding on retry.
• After 0.3.7: explicit HTTP error (Local REST API returns a 404/400 when the block is not found and creation is disabled) + no file mutation.

Your confirmation lets us close the block half of this thread cleanly. The heading half (partial-name → full-path resolution) remained covered by the 0.3.0 fix; if your root-level ## repro also works now, we can close the whole issue.

Cross-ref: istefox/obsidian-mcp-connector#6 for the PR itself.

[grimlor]

I had also fixed it on my branch that the PR on this thread mentions. I am now trying to figure out if I can get Jack to make me a maintainer. @istefox I'd love to collab as dual maintainers if we can make that happen.

[istefox]

Hey @grimlor — warm yes from me, and great news. Dual maintainership is healthier than solo from any direction, and having someone who's already been deep in the same territory makes the proposition concrete rather than hypothetical. Your PR #72 landed equivalently in the community fork's 0.3.0 (Create-Target-If-Missing is now a caller-controlled parameter on both patch_active_file and patch_vault_file), so we're already aligned on the core shape.

Quick context for the conversation with Jack:

• Fork continuation line — istefox/obsidian-mcp-connector shipped 0.3.0 → 0.3.7 covering most of the open issues here. Today's 0.3.7 takes PR fix(local-rest-api): replace hardcoded Create-Target-If-Missing with agent-controlled option #72 one step further for block targets specifically: default Create-Target-If-Missing is now false for targetType: "block" after @folotp documented the silent-corruption case with block ^id inside a markdown table cell. Heading and frontmatter keep the permissive true default for upstream compat. PR: istefox/obsidian-mcp-connector#6.
• Status audit — I posted a breakdown on Heads-up: maintenance status and a friendly community fork #79 of the 25 open issues upstream (fixed and credited in the fork / pending reporter confirmation / genuinely still open). Essentially a ready-made kickoff agenda for a co-maintainership team.
• Open questions for Jack — I asked three on Heads-up: maintenance status and a friendly community fork #79 (who's joining, team structure, response cadence). If you're in, that gives us a clean joint reply — something along the lines of "grimlor + istefox, here's what we propose". Happy to draft together.

Where do you want to sync? Options that come to mind:

• Continue on Heads-up: maintenance status and a friendly community fork #79 (public, already active — probably the right venue to bring Jack into the loop with both of us on record).
• Async chat — Discord or similar, if Jack opens one for maintainers.

Pick whichever you prefer and I'll follow your lead. Looking forward.

[folotp]

Heads-up @folotp — the block-in-table half of this issue is fixed in the community fork's v0.3.7, shipped today.

@istefox — confirming the v0.3.7 fix for the block-in-table half of this thread.

Test setup: Obsidian 1.12.7, Local REST API 3.6.1, mcp-tools-istefox 0.3.7.

Fixture (fixture-block-in-table.md):

Pre-table marker.

| Col1 | Col2 |
| --- | --- |
| Cell with block ref ^blk-in-cell | Other cell |
| Plain row | Plain |

Post-table marker.

Call:

{
  "operation": "replace",
  "targetType": "block",
  "target": "blk-in-cell",
  "content": "REPLACED"
}

Result on v0.3.7: explicit HTTP 400 with {"message":"The patch you provided could not be applied to the target content.\ninvalid-target","errorCode":40080}. File contents unchanged on disk (verified via get_vault_file after the call).

This is the expected post-fix shape — explicit error, no silent EOF append, no compounding on retry. The new per-target-type defaults you wired into Create-Target-If-Missing (block → false) are doing exactly what was needed.

The block half of this thread can close cleanly from my side. Thanks for the fast turnaround.

[folotp]

@istefox — separate finding from the v0.3.7 testing on the heading half of this thread. The root-level ## repro from my earlier comment still produces silent EOF append on v0.3.7. Reporting it here so the partial-fix scope is explicit.

Test setup: Obsidian 1.12.7, Local REST API 3.6.1, mcp-tools-istefox 0.3.7.

Fixture (fixture-h2-root.md, no frontmatter, no other headings):

## Section finale

Marker.

Call:

{
  "operation": "replace",
  "targetType": "heading",
  "target": "Section finale",
  "content": "REPLACED"
}

Result on v0.3.7: HTTP 200 with "File patched successfully", file content becomes:

## Section finale

Marker.
## Section finale
REPLACED

i.e. the original heading and body are untouched, and a duplicate ## Section finale + REPLACED is appended at EOF. Same canonical signature as the original bug.

Control tests (also on v0.3.7):

• H2 nested under H1 + same leaf-only call → in-place replace, works correctly.
• H1 at root + leaf-only call → in-place replace, works correctly.
• H2 nested under H1 with non-ASCII characters in the heading (Latin-1 accents, em-dash, NBSP) → in-place replace, works correctly. This confirms the v0.3.0 transport fix on patch_vault_file fails with non-ASCII heading names (Cyrillic, CJK, etc.) #78 is solid in isolation.

So the failure is specific to root-level H2 with no parent heading.

Plausible cause: the v0.3.0 leaf-only → full-path resolution in packages/mcp-server/src/features/local-rest-api/index.ts:419-422 correctly walks the tokenized headings to build a hierarchical path, but for a true-root H2 the resolved full path equals the leaf ("Section finale"). The PATCH then hits the upstream Local REST API / markdown-patch layer with the same target, which still doesn't index root-level H2 under any H1 key, and falls through to createTargetIfMissing. The wrapper-side resolution can't bridge that gap on its own.

Possible mitigations:

1. Wrapper-side detection. When the resolved full path equals the leaf and the target is not an H1, fail loud with invalid-target rather than passing through to the upstream silent-create path. Mirrors the per-target-type false default you shipped for block in v0.3.7.
2. Caller-controlled createTargetIfMissing: false for heading. Users who hit this case can opt out of the silent-create today. Worth surfacing in the README, since the upstream-compat default of true makes this case data-corrupting by default.
3. Upstream. Root-level H2 indexing is a markdown-patch / obsidian-local-rest-api concern. The hierarchical scanner would need to admit a synthetic root path so leaf-only targets at depth ≥ 2 with no H1 parent resolve to a stable key.

Happy to test any branch or alternative repro you'd like.

[istefox]

@folotp — fixed in v0.3.9 of the community fork (commit istefox/obsidian-mcp-connector@2342a6d).

The wrapper now pre-scans the file content (reusing the fetch that resolveHeadingPath already needed — no extra GET roundtrip) and rejects with McpError(InvalidParams, …) and an actionable message before the silent corruption can land. The error documents both workarounds: add a level-1 heading at the top of the file, or pass createTargetIfMissing=false to make the failure explicit.

End-to-end smoke test on your exact repro fixture (## Section finale\n\nMarker.) confirms the new behavior:

• Before 0.3.9: HTTP 200 + duplicate heading + content appended at EOF (your reported signature).
• After 0.3.9: MCP error -32602: Heading "Section finale" is a level-2 heading at the root of the file with no level-1 (#) parent... + file unchanged on disk.

12 regression tests pin the detection on detectOrphanRootHeading covering your exact repro plus the canonical valid cases (H1 root, H2 nested under H1, H3 under H1+H2), the orphan generalization to H3 and H3-under-orphan-H2, the first-match-wins ambiguity rule, and four defensive cases. Same family as the block-target silent EOF append fix in 0.3.7 — both are wrapper-side mitigations against markdown-patch indexer gaps.

Update via BRAT to pick it up. The upstream markdown-patch / obsidian-local-rest-api synthetic-root-path admission you suggested as option (3) in your comment is the right structural fix and would resolve this server-side too — but that's out of our control here. Closing the heading half from the fork side is the practical option in the meantime.

Thanks again for the rigorous bisect and the surgical mitigation suggestions in your follow-up — they made the fix easy to scope correctly.