{"record":{"id":"66b9a6a8c09536b4","repo":"facebook/docusaurus","slug":"there-was-an-error-extracting-tags-from-file-ta","errorCode":null,"errorMessage":"There was an error extracting tags from file: ${tagsFileInputResult.error.message}","messagePattern":"There was an error extracting tags from file: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils-validation/src/tagsFile.ts","lineNumber":121,"sourceCode":"    return null;\n  }\n  if (!yamlFilePath) {\n    throw new Error(\n      `No tags file '${relativeFilePath}' could be found in any of those directories:\\n- ${getContentPathList(\n        contentPaths,\n      ).join('\\n- ')}`,\n    );\n  }\n\n  const tagDefinitionContent = await fs.readFile(yamlFilePath, 'utf-8');\n  if (!tagDefinitionContent.trim()) {\n    return {};\n  }\n\n  const yamlContent = YAML.load(tagDefinitionContent);\n  const tagsFileInputResult = TagsFileInputSchema.validate(yamlContent);\n  if (tagsFileInputResult.error) {\n    throw new Error(\n      `There was an error extracting tags from file: ${tagsFileInputResult.error.message}`,\n      {cause: tagsFileInputResult},\n    );\n  }\n\n  const tagsFile = normalizeTagsFile(tagsFileInputResult.value);\n  ensureUniquePermalinks(tagsFile);\n\n  return tagsFile;\n}\n","sourceCodeStart":103,"sourceCodeEnd":132,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils-validation/src/tagsFile.ts#L103-L132","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before (tags.yml — invalid, bare string value)\nfoo: Foo Label\n\n# after (tags.yml — valid object)\nfoo:\n  label: Foo Label","handlingStrategy":"validation","validationCode":"import Joi from 'joi';\nimport YAML from 'js-yaml';\nimport fs from 'fs-extra';\n\nconst Schema = Joi.object().pattern(Joi.string(), Joi.object({\n  label: Joi.string(), description: Joi.string(), permalink: Joi.string(),\n}).allow(null));\n\nconst content = await fs.readFile(file, 'utf-8');\nconst result = Schema.validate(YAML.load(content));\nif (result.error) throw new Error(`tags.yml schema error: ${result.error.message}`);","typeGuard":"import Joi from 'joi';\n\nfunction isTagsFileInput(v: unknown): v is Record<string, { label?: string; description?: string; permalink?: string } | null> {\n  return !Joi.object().pattern(Joi.string(), Joi.object({\n    label: Joi.string(), description: Joi.string(), permalink: Joi.string(),\n  }).allow(null)).validate(v).error;\n}","tryCatchPattern":"try {\n  await getTagsFile({ tags, contentPaths });\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('There was an error extracting tags')) {\n    // show err.cause.error (the Joi validation result) to the author\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["tags","validation","yaml","schema","joi"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}