There was an error extracting tags from file: ${tagsFileInpu

Error message

There was an error extracting tags from file: ${tagsFileInputResult.error.message}

What it means

Thrown by getTagsFile() after loading and YAML-parsing the tags file when Joi schema validation against TagsFileInputSchema fails. The schema requires the top-level value to be an object whose keys are strings and whose values are objects with optional label/description/permalink string fields (or null). Any structural deviation — wrong types, arrays at the top level, non-string field values — produces this error with the underlying Joi message attached as the cause.

Source

Thrown at packages/docusaurus-utils-validation/src/tagsFile.ts:121

    return null;
  }
  if (!yamlFilePath) {
    throw new Error(
      `No tags file '${relativeFilePath}' could be found in any of those directories:\n- ${getContentPathList(
        contentPaths,
      ).join('\n- ')}`,
    );
  }

  const tagDefinitionContent = await fs.readFile(yamlFilePath, 'utf-8');
  if (!tagDefinitionContent.trim()) {
    return {};
  }

  const yamlContent = YAML.load(tagDefinitionContent);
  const tagsFileInputResult = TagsFileInputSchema.validate(yamlContent);
  if (tagsFileInputResult.error) {
    throw new Error(
      `There was an error extracting tags from file: ${tagsFileInputResult.error.message}`,
      {cause: tagsFileInputResult},
    );
  }

  const tagsFile = normalizeTagsFile(tagsFileInputResult.value);
  ensureUniquePermalinks(tagsFile);

  return tagsFile;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

Read the Joi error message embedded in the thrown error — it names the exact key and the constraint that failed.
Open tags.yml and ensure the structure is a flat map: each top-level key is a tag name, each value is an object with at most label, description, permalink (all strings), or null.
Validate the file with a YAML linter and fix indentation (use spaces, not tabs).
If a tag needs no metadata, set its value to null (the schema allows null) rather than omitting fields incorrectly.

Example fix

# before (tags.yml — invalid, bare string value)
foo: Foo Label

# after (tags.yml — valid object)
foo:
  label: Foo Label

Defensive patterns

Strategy: validation

Validate before calling

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

const Schema = Joi.object().pattern(Joi.string(), Joi.object({
  label: Joi.string(), description: Joi.string(), permalink: Joi.string(),
}).allow(null));

const content = await fs.readFile(file, 'utf-8');
const result = Schema.validate(YAML.load(content));
if (result.error) throw new Error(`tags.yml schema error: ${result.error.message}`);

Type guard

import Joi from 'joi';

function isTagsFileInput(v: unknown): v is Record<string, { label?: string; description?: string; permalink?: string } | null> {
  return !Joi.object().pattern(Joi.string(), Joi.object({
    label: Joi.string(), description: Joi.string(), permalink: Joi.string(),
  }).allow(null)).validate(v).error;
}

Try / catch

try {
  await getTagsFile({ tags, contentPaths });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('There was an error extracting tags')) {
    // show err.cause.error (the Joi validation result) to the author
  }
  throw err;
}

Prevention

Use a YAML-language-server-backed editor to validate tags.yml as you type.
Remember every tag value must be an object (or null), never a bare string or array.
Validate the schema in CI with a tiny script before running the full build.

When it happens

Trigger: Loading a tags.yml whose YAML structure does not match { tagName: { label?, description?, permalink? } }. Examples: a top-level list instead of a map, a tag value that is a bare string instead of an object, a permalink given as a number, or a tag value that is an array.

Common situations: Hand-editing tags.yml and dropping a field's nesting level (writing `foo: bar` instead of `foo: { label: bar }`). Pasting example content from a blog post that uses an older schema. YAML auto-coercion turning what looks like a string into a number or boolean. Mixing tab and space indentation causing YAML to parse into an unexpected shape.

Related errors

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