No tags file '${relativeFilePath}' could be found in any of

Error message

No tags file '${relativeFilePath}' could be found in any of those directories:
- ${getContentPathList(contentPaths).join('\n- ')}

What it means

Thrown by getTagsFile() when the tags option has been set to a string (a custom filename) but no matching file is found in either the localized content path or the base content path. The function uses getDataFilePath() to search both, and only returns null silently when tags is undefined (the retro-compatible case where a site has no tags.yml yet). Setting tags to any explicit value tells Docusaurus you intend to provide a tags file, so its absence is a hard error.

Source

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

  if (tags === false || tags === null) {
    return null;
  }

  const relativeFilePath = tags ?? DefaultTagsFileName;

  // if returned path is defined, the file exists (localized or not)
  const yamlFilePath = await getDataFilePath({
    contentPaths,
    filePath: relativeFilePath,
  });

  // If the tags option is undefined, don't throw when the file does not exist
  // Retro-compatible behavior: existing sites do not yet have tags.yml
  if (tags === undefined && !yamlFilePath) {
    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},
    );

View on GitHub (pinned to 3f483e80e3)

Solutions

Read the error: it lists every searched directory (the localized path first, then the base content path). Create the tags file in one of those exact directories.
Verify the filename you passed as the tags option matches the file on disk exactly (case-sensitive, with the .yml extension).
If you do not actually want a centralized tags file, remove the tags option (or set it to false / null) so getTagsFile returns null instead of throwing.
If you want the file auto-resolved by the default name, omit the tags option value and name the file tags.yml inside the content directory.

Example fix

// before (docusaurus.config.js)
plugins: [['@docusaurus/plugin-content-docs', { tags: 'tagz.yml' }]]
// typo: file is tags.yml on disk

// after
plugins: [['@docusaurus/plugin-content-docs', { tags: 'tags.yml' }]]

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs-extra';

async function tagsFileExists(contentPaths, relativeFilePath) {
  for (const dir of [contentPaths.contentPathLocalized, contentPaths.contentPath].filter(Boolean)) {
    if (await fs.pathExists(path.join(dir, relativeFilePath))) return true;
  }
  return false;
}

if (typeof tags === 'string' && !(await tagsFileExists(contentPaths, tags))) {
  throw new Error(`Config error: tags file '${tags}' not found in any content directory.`);
}

Type guard

function isTagsFileOption(v: unknown): v is string | boolean | null | undefined {
  return typeof v === 'string' || typeof v === 'boolean' || v === null || v === undefined;
}

Try / catch

try {
  await getTagsFile({ tags, contentPaths });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('No tags file')) {
    // create the file or unset the tags option
  }
  throw err;
}

Prevention

If you set the tags option to a custom filename, create the file at the same time you commit the config change.
Keep the tags file in the same content directory (docs/ or blog/) the plugin reads from.
Set tags: false explicitly if you do not want centralized tags, instead of leaving a stale filename.

When it happens

Trigger: A docs/blog plugin is configured with `tags: 'my-tags.yml'` (or `tags: true`) in docusaurus.config.js / plugin options, and that file does not exist in the content directory (docs/, blog/, or their i18n localized counterparts). The filename is misspelled, placed in the wrong directory, or the path is absolute when a relative one was expected.

Common situations: Renaming tags.yml without updating plugin config. Pointing tags at a file that lives in the repo root rather than the content folder. On Windows, casing mismatches in the filename. Setting `tags: true` expecting Docusaurus to create the file automatically — it does not, you must author it.

Related errors

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