Missing YAML frontmatter. The file must start with `---` fol

Error message

Missing YAML frontmatter. The file must start with `---` followed by YAML fields and a closing `---`.

What it means

After a successful read, parseFrontmatter (line 38) runs the regex /^---\r?\n([\s\S]*?)\r?\n---/. If it returns null the validator reports 'Missing YAML frontmatter' and returns at line 104. The regex requires a newline immediately after the opening `---` and immediately before the closing `---`, so a file beginning with `--- ` (trailing whitespace), `---title:...` (no newline), or a BOM/leading blank line will not match.

Source

Thrown at .github/scripts/validate-companies.js:102

 * Validate a single company file. Returns an array of error strings.
 */
function validateCompanyFile(filePath) {
  const errors = [];
  const warnings = [];
  let content;

  try {
    content = readFileSync(filePath, "utf-8");
  } catch (err) {
    errors.push(`Could not read file: ${err.message}`);
    return { errors, warnings };
  }

  // Parse frontmatter
  const data = parseFrontmatter(content);
  if (!data) {
    errors.push(
      "Missing YAML frontmatter. The file must start with `---` followed by YAML fields and a closing `---`."
    );
    return { errors, warnings };
  }

  // Check required fields
  for (const field of REQUIRED_FIELDS) {
    if (!data[field] || (typeof data[field] === "string" && !data[field].trim())) {
      errors.push(`Missing required field: \`${field}\``);
    }
  }

  // Validate enum values (only if field exists)
  if (data.region && !VALID_REGIONS.includes(data.region)) {
    errors.push(
      `Invalid \`region\`: "${data.region}". Must be one of: ${VALID_REGIONS.join(", ")}`
    );
  }

View on GitHub (pinned to b1dd8deb19)

Solutions

Ensure the file starts literally with `---` followed by a newline, no leading characters.
Remove any UTF-8 BOM (`sed -i '1s/^\xEF\xBB\xBF//' file.md`).
Close the frontmatter block with `---` on its own line.
Re-run the validator to confirm the error clears.

Example fix

// before
# Acme Corp

Acme is a company...
// after
---
title: "Acme Corp"
slug: acme-corp
---

## Company blurb

Acme is a company...

Defensive patterns

Strategy: validation

Validate before calling

function hasFrontmatter(content) {
  return /^---\r?\n[\s\S]*?\r?\n---/.test(content);
}
// before submitting:
if (!hasFrontmatter(readFileSync(file, 'utf-8'))) {
  fail('file must start with a ---\n...\n--- frontmatter block');
}

Type guard

function hasFrontmatter(content) {
  return typeof content === 'string' && /^---\r?\n[\s\S]*?\r?\n---/.test(content);
}

Prevention

Start every new profile from a template that already has the fences.
Exclude the frontmatter fences from editor trim-whitespace-on-save.
Strip any UTF-8 BOM from contributed files.

When it happens

Trigger: File begins with prose instead of `---\n`; opening fence has trailing whitespace (`--- `); opening fence lacks a following newline; a UTF-8 BOM sits before the first `---`; the frontmatter block was deleted during a merge; the file uses `~~~` instead of `---`.

Common situations: Contributor writes pure markdown without frontmatter; editor auto-trims trailing whitespace on save and corrupts the fence; BOM injected by a Windows editor; autoformatter inserts a leading blank line.

Related errors

AI-assisted analysis of remoteintech/remote-jobs@b1dd8deb19 (2026-08-13). Data as JSON: /api/errors/4bdc3547867b6137. Report an issue: GitHub.