Home › Reference

Diagnostics

Extraction never fails silently. Unresolved or malformed constructs emit structured diagnostics:

src/Widget.luau:42: warning[orphaned-within]: @within Panel: no class or module with that name

luaudocs build --emit-only prints all diagnostics without running VitePress, and --strict fails the build on any warning.

Extractor diagnostics carry a file location and code. Renderer and site-sync warnings apply to the site as a whole (without a source file or code) and also count toward --strict.

Severity levels

• error: fails the build. Valid module pages are still emitted and existing pages and navigation stay on disk, but stale-page cleanup and VitePress are skipped and the CLI exits nonzero.
• warning: printed to stderr. Exits nonzero only under --strict.
• info: printed dimmed. Never affects the exit code, even under --strict.

Errors

Code	What it means
parse-error	A file in the module graph could not be read or parsed (syntax error or deleted file).
extract-failed	The symbolic evaluator hit an internal error analyzing a module. Please report it.

Warnings

Code	What it means
require-unresolved	A surfaced require target could not be resolved (missing file, unknown .luaurc alias, path outside the project, or top-level dynamic assignment such as M.Sub = require(target)). Dynamic helper parameters inside functions (return require(mod)) do not warn, and runtime aliases (@lute, @lune, or [source.aliases]) are treated as external.
orphaned-within	@within Name names no known class or module.
duplicate-within	Two members collide under the same name after @within relocation. The second is dropped.
duplicate-class	Two blocks in one module declare @class with the same name. The duplicate is dropped (see also Info).
duplicate-external	Two @external tags map the same name. The first wins.
duplicate-type	A type name is declared more than once in a module. The exported (or first) declaration is kept.
param-mismatch	@param name doesn't match any parameter in the function signature.
return-count-mismatch	More @return tags than return values in the signature.
duplicate-member	Two definitions resolve to the same member ID in one container. The later definition is dropped.
malformed-tag	A tag requiring a name or URL was written without one (such as a bare @param).
unknown-tag-arg	A flag tag (such as @yields) was given an unexpected argument.
duplicate-placing-tag	Multiple placement tags appear in one doc block (@class and @prop). The first wins.
undocumented	A public member, class, or exported type has no doc comment (emitted when [api] reportUndocumented is enabled).

Info

Code	What it means
surface-opaque	A module's return value could not be evaluated statically. See Nothing was generated.
orphaned-doc-block	A doc comment with tags (@param, @within) sits above no statement. Plain prose comments are ignored.
unresolved-reexport	A re-export targets a symbol its source module doesn't document.
require-nonmodule	A surfaced require resolved to a Folder or non-module path (script.Parent.Assets), leaving no module script to follow.
duplicate-class	A floating @class names a class that already exists. Members aimed at that name merge into the existing class.
ignored-tag	@__index, accepted for Moonwave compatibility and ignored.
unreached-types	An unexposed module (such as an internal types.luau) exports types never referenced by a documented signature. Add the module to [source] entries, move types with @within, or re-export them (export type Hook = types.Hook).

Renderer warnings

Prefixed with renderer::

Message	What it means
page name collision	Two modules share a page slug. The second gets a numbered slug and a parent-qualified title (Defaults (Flux)).
ambiguous reference name dropped from link table	A [Ref] name matches two equal-standing targets (modules outrank same-named types without warning). Qualify the reference ([Module.State]) or rename.
aliases.<name>: could not load its doc model	A [source.aliases] model URL or path could not be loaded, so links fall back to module pages. Counts toward --strict.

Site-sync warnings

Emitted during site file synchronization (all count toward --strict):

Message	What it means
[docs] changelog is enabled but CHANGELOG.md was not found	[docs] changelog = true is set, but CHANGELOG.md is missing.
[docs] includeReadme is enabled but README.md was not found	[docs] includeReadme = true is set, but README.md is missing.
index.md includes .vitepress/generated/readme.md, which only [docs] includeReadme = true keeps	Custom index.md includes .vitepress/generated/readme.md while includeReadme is disabled.
README.md links …, which the generated site does not serve	A relative link in README.md points outside the docs directory and [repo] url is unset or can't reach it.