jsdoc "ERROR: Unable to parse a tag's type expression"

TL;DR: Fix the malformed {...} type expression in the comment jsdoc names. "Unable to parse a tag's type expression" means a @param, @returns, or similar tag has braces jsdoc's parser cannot read - usually a missing closing brace or a stray character. Open the file and line from the error, repair the expression, and re-run jsdoc.

ERROR: Unable to parse a tag's type expression

1. Reproduce and get the location:

   npx jsdoc -c jsdoc.json 2>&1 | grep -B2 "Unable to parse"

Expected: the lines above the error name the source file and line number.

1. Open that comment and inspect every {...} expression. The usual breaks are a missing closing brace ({string), an unclosed union ({string | number), or bracket syntax the parser does not know.
2. Rewrite it plainly, for example:

   @param {string} name - the user's name
   @param {string[]} tags - list of tags
   @returns {Promise} a promise for the result

1. Re-run jsdoc:

   npx jsdoc -c jsdoc.json

Expected: no ERROR lines, and the output directory contains the generated pages.

1. If many files fail at once, fix them one file at a time and keep a passing baseline so new breaks are obvious.

Use this when

• jsdoc exits with "Unable to parse a tag's type expression"
• The error names a specific file and line in a doc comment
• A docs build that used to pass now fails after comment edits

Not for this skill when

• jsdoc warns about an unknown tag name - that is a tag problem, not a type-expression problem
• The build fails because a source file cannot be found - check source.include in the config
• You want TypeScript-style types checked - jsdoc parses types loosely; use tsc for real type checking

Variant phrasings

• "jsdoc unable to parse type expression"
• "jsdoc type expression parse error"
• "Unable to parse a tag's type expression for source file"

Why it happens

jsdoc parses the {...} after a tag with its own type-expression grammar. Anything outside that grammar - unbalanced braces, stray pipes or commas, bracket styles it does not know - makes the whole tag unparseable, and jsdoc treats that as a hard error rather than skipping the tag.

Edge cases

• {*} means "any type" and always parses; prefer it over inventing syntax for unknown types.
• Union types need every branch closed: {string | number} is fine, {string | number is not.
• Optional parameters use brackets around the name (@param {string} [name]), not inside the type braces.
• Nullable and non-nullable markers ({?string}, {!string}) must wrap the whole type, not part of it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst2kf-L7jzX1MIseA-iAAaw