typedoc "Warning: unknown @tag in comment"

TL;DR: the warning means TypeDoc saw a doc-comment tag it does not recognize. Fix it at the source: correct the tag spelling, enable the plugin that defines the tag, or declare the tag in tsdoc.json.

The verbatim error:

Warning: unknown @tag in comment

Fix

1. Find the exact tag in the warning. TypeDoc logs the offending tag name (e.g. @params, @component, @myTag). Grep your sources for it:

   • Expected: the exact tag name and the file/line that produced the warning.

2. Check spelling against TypeDoc's tag list. The two classics are @params (wrong) vs @param (right), and @return (wrong, that is JSDoc) vs @returns (right).

   • Expected: typo corrected, warning gone for that file.

3. If the tag comes from a plugin (e.g. @category from typedoc-plugin-rename-defaults-style tags, or a custom renderer plugin), make sure the plugin is actually loaded in your TypeDoc config:

   {
     "plugin": ["typedoc-plugin-xyz"]
   }

   • Expected: the warning disappears once the defining plugin is registered, because TypeDoc now knows the tag.

4. If it is your own custom tag, declare it in tsdoc.json so the TSDoc parser accepts it:

   {
     "tsdocConfig": {
       "tagDefinitions": [
         {
           "tagName": "@myTag",
           "syntaxKind": "block",
           "allowMultiple": false
         }
       ]
     }
   }

   • Expected: typedoc runs clean with no unknown @tag warnings.

5. Re-run TypeDoc and confirm zero warnings for the tag.

   • Expected: exit 0 and no Warning: unknown lines in output.

When to use

• Any TypeDoc build logging Warning: unknown @... in comment for a tag you actually intend to keep.
• After adding a TypeDoc plugin whose tags now warn as unknown.
• When adopting TSDoc validation in an existing codebase and surfacing legacy tags.

When NOT to use

• If the warning names a tag you do not recognize and never wrote: it is probably stray text starting with @ in a comment (e.g. an email address or @2024). Just reword or backtick-quote the text instead of declaring a tag.
• If the goal is simply silencing the warning without fixing docs: do not declare junk tags to hide real typos; fix the typo.

Compatibility

• TypeDoc 0.23+ (tags are validated against the known tag set; custom tags need tsdoc.json).
• TSDoc parser backing TypeDoc's comment parser (0.14+ supports tagDefinitions in tsdoc.json).
• Behavior is the same for typedoc.json, CLI flags, and API options; only the config file shape differs.

Variant phrasings

• typedoc warning unknown block tag
• TypeDoc: Warning: The tag @x is not recognized in this context
• typedoc unknown inline tag

Root cause

TypeDoc parses doc comments with a TSDoc parser that only accepts a closed set of tags (TypeDoc's own list plus whatever plugins and tsdoc.json declare). Any @tag outside that set is reported as unknown. The three causes are always: a typo, a plugin that defines the tag but is not loaded in the run that warns, or a custom tag nobody declared. The warning is informational, but an unrecognized tag also means the tag's content is dropped from the rendered docs, so it is never just noise.

Edge cases

• Plugins loaded via typedoc --plugin on the CLI but missing from typedoc.json will warn in CI where the CLI flags are not passed: keep plugin registration in the config file.
• Monorepos: a root tsdoc.json does not automatically apply to packages with their own TypeDoc runs; declare per-package or point tsdoc at the shared file.
• Inline tags ({@link ...}, {@inheritDoc}) warn the same way when misspelled, e.g. {@linkk}: same fix, check spelling.
• @returns vs @return: TypeDoc accepts @returns; @return warns as unknown.

Source: vectle-weak-query thread pst_iOfyyM6Zcbu3LhYYuZxWvg (external guest query "typedoc Warning unknown tag in comment" returned weak results, top score 0.43). Fix family verified against TypeDoc docs: TSDoc tagDefinitions schema in tsdoc.json, typedoc plugin registration in typedoc.json.