affaan-m/ECC · error · Error

Invalid memory frontmatter line in ${sourcePath}.

Error message

Invalid memory frontmatter line in ${sourcePath}.

What it means

Thrown by parseFrontmatterLine() when a line in the frontmatter block has no ':' separator, or the ':' is at index 0 (empty key). Every frontmatter line must be of the form 'serialized_key: JSON-value'. Lines that are blank, comments, plain prose, or use '=' instead of ':' are rejected — the parser is intentionally YAML-subset-strict to avoid ambiguous parsing.

Source

Thrown at scripts/lib/memory-vault-format.js:225

  const metadata = FRONTMATTER_FIELDS.map(([serializedKey, objectKey]) => (
    `${serializedKey}: ${JSON.stringify(normalized[objectKey])}`
  )).join('\n');
  const body = normalized.body.length > 0 ? `\n\n${normalized.body}` : '';
  return `---\n${metadata}\n---${body}\n`;
}

function decodeUtf8(buffer, label = 'text') {
  try {
    return FATAL_UTF8_DECODER.decode(buffer);
  } catch {
    throw new Error(`${label} must contain valid UTF-8 text.`);
  }
}

function parseFrontmatterLine(line, sourcePath, seen) {
  const separator = line.indexOf(':');
  if (separator <= 0) {
    throw new Error(`Invalid memory frontmatter line in ${sourcePath}.`);
  }
  const serializedKey = line.slice(0, separator).trim();
  const objectKey = FRONTMATTER_KEYS.get(serializedKey);
  if (!objectKey) {
    throw new Error(`Unknown memory frontmatter field in ${sourcePath}.`);
  }
  if (seen.has(objectKey)) {
    throw new Error(`Duplicate memory frontmatter field in ${sourcePath}.`);
  }
  const rawValue = line.slice(separator + 1).trim();
  try {
    return { objectKey, value: JSON.parse(rawValue) };
  } catch {
    throw new Error(`Memory frontmatter field in ${sourcePath} must use a JSON value.`);
  }
}

function parseMemoryDocument(source, sourcePath = '<memory>') {

View on GitHub (pinned to 01e15490f0)

Solutions

1. Open the file at the path reported in sourcePath and inspect each frontmatter line for a missing colon.
2. Remove blank lines and comments from between the --- markers; comments belong in the body.
3. Always use the form 'key: <JSON-value>' — for strings that means 'key: "value"'.
4. Regenerate the file via serializeMemoryDocument(memory) rather than hand-editing.

Example fix

// before — file contents
---
title "handoff"          # missing colon
# author: bob            # comment line inside frontmatter
kind: note
---

// after
---
title: "handoff"
kind: "note"
---

function isValidFrontmatterLine(line) {
  const sep = line.indexOf(':');
  return sep > 0;
}
lines.forEach(line => {
  if (line.length > 0 && !isValidFrontmatterLine(line)) {
    throw new Error(`frontmatter line is malformed: ${JSON.stringify(line)}`);
  }
});

try {
  parseMemoryDocument(source, path);
} catch (err) {
  if (/Invalid memory frontmatter line/.test(err.message)) {
    reportToUser(path, 'each frontmatter line must be "key: <JSON-value>"');
  }
  throw err;
}

When it happens

Trigger: A memory file containing a blank line inside the frontmatter block, a comment like '# this is the title', a line 'title = My Note' using TOML/INI syntax, or a line that is just 'title' with the value on the next line.

Common situations: User hand-edited the .md file and added a comment. Editor auto-inserted a blank line on save. Copy-paste from a YAML file that uses 'key: value' but with leading whitespace that confused the parser. AI agent wrote frontmatter without the colon when the value was empty.

Related errors

• Unknown memory frontmatter field in ${sourcePath}.
• Duplicate memory frontmatter field in ${sourcePath}.
• Memory frontmatter field in ${sourcePath} must use a JSON va
• Memory document ${sourcePath} must start with --- frontmatte
• Memory document ${sourcePath} has no closing frontmatter mar

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/6eff596db43b7af2. Report an issue: GitHub.