The file at path=${path.relative(process.cwd(), filePath)} l

Error message

The file at path=${path.relative(process.cwd(), filePath)} looks invalid (not Yaml nor JSON).

What it means

Thrown by readDataFile() when the targeted data file exists and is read successfully but js-yaml's YAML.load() throws while parsing it. readDataFile supports YAML (and YAML's JSON superset), so a parse failure means the content is neither valid YAML nor valid JSON. The original parse error is attached as {cause: err} for diagnostics.

Source

Thrown at packages/docusaurus-utils/src/dataFileUtils.ts:67

 * It is the caller responsibility to validate and normalize the resulting data
 *
 * @returns `undefined` when file not found
 * @throws Throws when data file can't be parsed
 */
export async function readDataFile(params: DataFileParams): Promise<unknown> {
  const filePath = await getDataFilePath(params);
  if (!filePath) {
    return undefined;
  }
  try {
    const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
    return Yaml.load(contentString);
  } catch (err) {
    const msg = logger.interpolate`The file at path=${path.relative(
      process.cwd(),
      filePath,
    )} looks invalid (not Yaml nor JSON).`;
    throw new Error(msg, {cause: err});
  }
}

/**
 * Takes the `contentPaths` data structure and returns an ordered path list
 * indicating their priorities. For all data, we look in the localized folder
 * in priority.
 */
export function getContentPathList(contentPaths: ContentPaths): string[] {
  return [contentPaths.contentPathLocalized, contentPaths.contentPath].filter(
    (p) => p !== undefined,
  );
}

/**
 * @param folderPaths a list of absolute paths.
 * @param relativeFilePath file path relative to each `folderPaths`.
 * @returns the first folder path in which the file exists, or `undefined` if

View on GitHub (pinned to 3f483e80e3)

Solutions

Inspect the cause property of the thrown error — js-yaml reports the exact line/column of the syntax violation.
Open the file at that location and fix the syntax (replace tabs with spaces, balance quotes, remove trailing commas).
Validate the file independently with a YAML or JSON linter before rebuilding.
If the file should not be interpreted as data, move it out of the content path or rename it so readDataFile no longer picks it up.

Example fix

# before (sidebar.yml — tab-indented, invalid)
items:
	- doc1

# after (sidebar.yml — space-indented)
items:
  - doc1

Defensive patterns

Strategy: validation

Validate before calling

import YAML from 'js-yaml';
import fs from 'fs-extra';

function tryParseYamlOrJson(content: string): unknown {
  try { return YAML.load(content); }
  catch (yamlErr) {
    try { return JSON.parse(content); }
    catch (jsonErr) {
      throw new Error(`Unparseable data file: yaml=${yamlErr.message} json=${jsonErr.message}`);
    }
  }
}

// pre-validate before readDataFile is called
const content = await fs.readFile(filePath, 'utf8');
tryParseYamlOrJson(content);

Try / catch

try {
  await readDataFile(params);
} catch (err) {
  if (err instanceof Error && err.message.includes('looks invalid')) {
    // err.cause has the js-yaml parse details (line/column)
  }
  throw err;
}

Prevention

Use spaces, never tabs, for YAML indentation.
Avoid trailing commas in JSON-superset YAML files.
Add a YAML lint step to CI for all data files Docusaurus reads.

When it happens

Trigger: Calling readDataFile() with a contentPaths/filePath combination pointing at a file whose contents violate YAML syntax: mixed tabs/spaces for indentation, unclosed quotes, duplicate keys in a mapping, or a stray control character. Also thrown if the file is actually binary or text in an unrelated format but was placed where Docusaurus expects a data file.

Common situations: Editing a sidebar or tags data file with an editor that inserts tabs. A copy-paste from a rich-text source that introduced smart quotes or non-breaking spaces. A JSON file with a trailing comma (valid in JSON5/JS but rejected by strict YAML/JSON parsers). An accidental save of a Markdown document into a .yml path.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/9b2bc680c16918f0. Report an issue: GitHub.