Indexing crashes with KeyError when note content reaches loguru message formatting

[phernandez]

Problem

Production note indexing jobs crash with KeyError raised from inside loguru's message formatting, exhaust all 5 PGQueuer attempts, and terminally fail. The affected notes never index until a later unrelated touch.

Logfire issues (basic-memory-cloud project): #2391 e41e60d1-3f50-4fb8-84ff-ae7c676ff4e8 (entrypoint index_file) and #2393 65936064-3a57-4b61-90e8-347ea8d55dda (entrypoint index_file_batch), both 2026-08-08.

Representative traces (auth-gated):

• #2391 latest
• #2393 latest

Root cause (trace-proven)

Both stacktraces bottom out identically:

basic_memory.index.local_dependencies.index_markdown_file:345
loguru._logger.info:2078
loguru._logger._log:2055
KeyError: <customer-derived key, redacted>

Line 345 is the retry log emitted between attempts of the note-content reconcile loop. Customer-derived text (a note path/title) reaches loguru's message-formatting path, and when that text contains literal braces — e.g. template-style notes containing {placeholder} — loguru interprets them as format fields and raises KeyError on the customer's own text. The exception escapes the reconcile loop, the job retries with identical bytes, and all 5 attempts fail the same way.

The KeyError values observed in production are single capitalized words consistent with template placeholders inside customer note names/content. They are redacted here; see the Logfire traces.

Impact

• Any note whose path/title/content puts brace-wrapped text into this log line can never be indexed by the retry path — a durable indexing gap for that customer, invisible to them.
• The failure is deterministic per note, so retries are pure waste (5 deliveries per event).

Fix

Never route customer-derived strings through loguru's format path at this call site (and audit the sibling log calls in the same loop): pass values as structured arguments/extra fields rather than interpolated message text, or escape braces. No behavior change to indexing itself.

Acceptance criteria

• Indexing a note whose filename/title contains literal {braces} completes and the retry log line renders safely.
• Regression test covering the reconcile-loop retry log with brace-containing content.
• Audit of other log statements in index_markdown_file/reconcile loop for the same pattern.
• Production soak shows no recurrence of Logfire #2391/#2393.

[claude]

Claude finished @phernandez's task in 2m 0s —— View job

---

Triage complete

• Read issue and repository guidelines
• Classify issue type, priority, component, complexity
• Check for duplicate issues
• Apply labels
• Post triage summary comment

Type: Bug (code defect)
Priority: High — deterministic, silent indexing failure for any note whose path/title/content contains literal braces; exhausts all 5 PGQueuer retries and leaves the note permanently unindexed until an unrelated touch. No data loss, so not Critical.
Component: Cloud indexing pipeline (PGQueuer index_file / index_file_batch entrypoints), core code lives in src/basic_memory/index/local_dependencies.py.
Complexity: Simple — logging-call fix, no behavior change to indexing itself.

Duplicate check: Searched open/closed issues for loguru, KeyError, and index_markdown_file — no existing issue covers this. Not a duplicate.

Labels applied: cloud (in addition to the existing bug label). Note: this repo's label set does not currently include priority-tier or complexity-tier labels (e.g. high, simple, priority-high), so those assessments above are recorded here as text only.

Root cause confirmed in code: I read src/basic_memory/index/local_dependencies.py and the exact vulnerable call is at what is now line 345-346:

logger.info(
    f"Indexed markdown file: {file_path}",
    entity_id=synced.entity.id,
    checksum=synced.checksum,
    operation=operation,
    ...
)

Because the message is built with an f-string, file_path is interpolated into the literal message text before loguru sees it. loguru then treats that resulting string as a str.format() template (since keyword args like entity_id= are also passed), so any literal { / } characters carried in file_path (e.g. a note path/title containing {placeholder}) are parsed as format fields — and since no such field was supplied, .format() raises KeyError on the customer's own text. This matches the loguru._logger.info → _log → KeyError traces in Logfire #2391/#2393.

I found two other f-string log calls in the same file worth including in the audit called for in the acceptance criteria, since they interpolate the same customer-controlled file_path/path value into the message text:

• local_dependencies.py:295 — logger.info(f"Indexing markdown file: {file_path}") (no extra kwargs currently, lower risk but still fragile if kwargs are added later)
• local_dependencies.py:370 — logger.info(f"Indexing regular file: {file_path}", source=source) — same pattern as the crash site (f-string + kwargs)
• local_dependencies.py:439 — logger.debug(f"Parsing markdown file, path: {path}, new: {new}") (no kwargs currently)

The line 334-339 retry log ("Retrying markdown index after concurrent accepted note write: {}", file_path) is not affected — it correctly uses loguru's own {} positional placeholder rather than pre-interpolating via an f-string, so brace characters inside file_path are substituted as a value, not re-parsed as template syntax.

This is triage only, per scope — no fix has been implemented. The straightforward remediation (not applied here) would be to stop pre-interpolating customer-derived strings into the message via f-strings at these call sites, passing them as positional/keyword arguments to logger.info/logger.debug instead (or escaping literal braces) so loguru's formatting pass can't re-parse them.