affaan-m/ECC · error · Error

Invalid memory frontmatter line in

Error message

Invalid memory frontmatter line in ${sourcePath}.

What it means

parseFrontmatterLine() parses one `key: value` line of a memory document's frontmatter. It requires a colon at position > 0 (i.e. a non-empty key followed by a colon). A line without any colon, or starting with a colon, is structurally invalid frontmatter and is rejected with the source path in the message.

Solutions

1. Give every frontmatter line the form `key: value` with a non-empty known key before the colon.
2. Remove stray prose, blank-formatted, or indented continuation lines from inside the --- block.
3. Use only the supported frontmatter keys (see FRONTMATTER_KEYS); nested YAML structures are not supported.
4. Re-save the memory via the library's write path instead of hand-editing to regenerate well-formed frontmatter.

Example fix

// before
---
title Deploy notes
schema: 1
---

// after
---
title: "Deploy notes"
schema: 1
---

const lines = frontmatterBlock.split('\n');
lines.forEach(l => { if (!/^[^:\s][^:]*:/.test(l)) throw new Error(`Malformed frontmatter line: ${l}`); });

const isWellFormedLine = (line) => /^[^:\s][^:]*:/.test(line);

try {
  const parsed = parseMemoryDocument(source, path);
} catch (err) {
  if (err.message.includes('Invalid memory frontmatter line')) {
    const lineNo = findOffendingLine(source); // locate and report
    console.error('Frontmatter line %d in %s has no `key:` separator.', lineNo, path);
  } else throw err;
}

When it happens

Trigger: A frontmatter line like `title Deploy notes` (missing colon), `: value` (empty key), stray text lines inside the --- block, or a key containing only whitespace before the colon; also triggered by a colon-only line or tab-formatted continuation lines.

Common situations: Hand-editing the markdown vault and deleting a colon; a YAML-style block (nested keys, lists, multi-line values) pasted into frontmatter that only supports flat `key: JSON-value` lines; markdown linters reformatting lines.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Memory document must start with --- frontmatter.
• Duplicate memory frontmatter field in
• Memory frontmatter field in
• Unknown memory frontmatter field in
• bad timecode

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/6eff596db43b7af2. Report an issue: GitHub.

Appendix: 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 8321021c54)