update_frontmatter logs errors for malformed YAML instead of handling gracefully

[phernandez]

Summary

The update_frontmatter() function in file_utils.py logs level 17 errors when encountering malformed YAML frontmatter, even though the system should handle these gracefully.

Evidence from Production

Last 3 hours: 1,112 errors of "Failed to update frontmatter"

All errors are from files with colons in titles that confuse the YAML parser:

---
title: KB: Something  # The second colon breaks YAML
---

Error Pattern:

Failed to update frontmatter
mapping values are not allowed here in "<unicode string>", line 2, column 10

Affected Files: 22+ files with KB: prefix in titles

Root Cause

PR #368 fixed YAML error handling in entity parsing (reading files), but update_frontmatter() has a separate code path that wasn't fixed:

Location: src/basic_memory/file_utils.py:188-237

async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
    try:
        # ...
        if has_frontmatter(content):
            current_fm = parse_frontmatter(content)  # ← Raises ParseError for YAML errors
            # ...
    except Exception as e:  # pragma: no cover
        logger.error(  # ← Logs as ERROR (level 17)
            "Failed to update frontmatter",
            path=str(path),
            error=str(e),
        )
        raise FileError(f"Failed to update frontmatter: {e}")

Impact

• Log Spam: 1,112 errors in 3 hours from same files retrying
• Misleading Severity: Files are actually processed fine, errors are cosmetic
• Monitoring: Real errors get buried in YAML parsing noise
• User Confusion: Errors appear critical but have no actual impact

Expected Behavior

Should match PR #368's handling in entity parser:

1. Catch YAML parsing errors gracefully
2. Log WARNING (level 13) instead of ERROR
3. Treat file as having no frontmatter
4. Proceed with the update using new frontmatter

Proposed Fix

Update update_frontmatter() to handle YAML errors like entity_parser.py does:

async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
    try:
        path_obj = Path(path) if isinstance(path, str) else path
        content = path_obj.read_text(encoding="utf-8")
        
        # Parse current frontmatter with error handling
        current_fm = {}
        if has_frontmatter(content):
            try:
                current_fm = parse_frontmatter(content)
                content = remove_frontmatter(content)
            except (ParseError, yaml.YAMLError) as e:
                # Log warning and treat as plain markdown
                logger.warning(
                    f"Failed to parse YAML frontmatter in {path_obj}: {e}. "
                    "Treating file as plain markdown without frontmatter."
                )
                # Keep full content, treat as having no frontmatter
                current_fm = {}
        
        # Update frontmatter
        new_fm = {**current_fm, **updates}
        
        # Write new file with updated frontmatter
        yaml_fm = yaml.dump(new_fm, sort_keys=False, allow_unicode=True)
        final_content = f"---\n{yaml_fm}---\n\n{content.strip()}"
        
        await write_file_atomic(path_obj, final_content)
        return await compute_checksum(final_content)
        
    except Exception as e:
        # Only log real errors (not YAML parsing)
        if not isinstance(e, (ParseError, yaml.YAMLError)):
            logger.error(
                "Failed to update frontmatter",
                path=str(path),
                error=str(e),
            )
        raise FileError(f"Failed to update frontmatter: {e}")

Priority

P1 - High volume of error logs in production affecting monitoring and observability. Quick fix, same pattern as PR #368.

Related

• PR fix: Handle YAML parsing errors and missing entity_type in markdown files #368 - Fixed similar issue in entity parser
• Issue basicmachines-co/basic-memory-cloud#185 - YAML parsing errors (fixed in entity parser, not in update_frontmatter)

Success Criteria

1. YAML parsing errors logged as WARNING (level 13) not ERROR (level 17)
2. Error count drops from 1,112/3hrs to ~0
3. Files with malformed frontmatter still get updated successfully
4. Real file operation errors still logged as ERROR

[claude]

Claude finished @phernandez's task —— View job • claude/issue-378-20251017-0005 • Create PR ➔

---

Fix Completed for Issue #378

Issue Triage:

• Type: Bug (error handling defect)
• Priority: High (1,112 errors/3hrs in production)
• Component: File operations (file_utils.py)
• Complexity: Simple (clear fix pattern from PR fix: Handle YAML parsing errors and missing entity_type in markdown files #368)

Tasks

• Read current file_utils.py implementation
• Review PR fix: Handle YAML parsing errors and missing entity_type in markdown files #368 error handling pattern
• Add labels to issue (skipped - no permission)
• Update update_frontmatter() to handle YAML errors gracefully
• Add test for malformed YAML case
• Run test suite to verify fix (skipped - no permission)
• Run linter and type checker (skipped - no permission)
• Commit and push changes
• Provide PR creation link

Changes Made

1. Updated src/basic_memory/file_utils.py:188-247:

• Added try/except around parse_frontmatter() call to catch ParseError and yaml.YAMLError
• Changed logging from ERROR (level 17) to WARNING (level 13) for YAML parsing failures
• Files with malformed frontmatter now treated as plain markdown without frontmatter
• Updated outer exception handler to only log ERROR for real file operation failures, not YAML parsing

2. Added test in tests/utils/test_file_utils.py:262-295:

• New test test_update_frontmatter_malformed_yaml() verifies graceful handling
• Tests the exact scenario from production: title: KB: Something
• Confirms frontmatter update succeeds and content is preserved
• Validates new frontmatter is well-formed YAML

Expected Impact

This fix should:

• ✅ Reduce ERROR logs from 1,112/3hrs to ~0
• ✅ YAML parsing issues logged as WARNING instead of ERROR
• ✅ Files with malformed frontmatter (e.g., "KB: Something") successfully updated
• ✅ Real file operation errors still logged as ERROR
• ✅ Matches the error handling pattern from PR fix: Handle YAML parsing errors and missing entity_type in markdown files #368

Next Steps

---

Branch: claude/issue-378-20251017-0005