All Diagnostics

Complete reference of every diagnostic code. For an introduction to how diagnostics work and how to configure them, see the Diagnostics guide.

Error severity

Code	Description
syntax	Lua syntax error: code that doesn't parse
safety-limit	Analysis of the file hit an internal limit and stopped early, so some types and diagnostics may be missing. Reported at the top of the file

Warning severity

Code	Description
deprecated	Call to a function marked @deprecated (flavor-aware: suppressed when the API is still live in a flavor the addon targets; see Flavor Filtering)
discard-returns	Ignoring @nodiscard return values
type-mismatch	Argument type vs @param mismatch (including generic type arguments, e.g. Container<number> vs Container<boolean>, and string-literal unions, e.g. "x" against "A"|"B"|"C")
return-mismatch	Return type vs @return mismatch
field-type-mismatch	Field assignment vs @field type mismatch
assign-type-mismatch	Reassignment vs @type mismatch
generic-constraint-mismatch	Generic argument doesn't satisfy a class, alias, or keyof constraint
param-constraint-mismatch	Method called when the receiver's @requires type-param constraint isn't satisfied
missing-parameter	Missing required function arguments
redundant-parameter	Extra function arguments
missing-return-value	Return with fewer values than @return
redundant-return-value	Return with more values than @return
grouped-return-mismatch	Return values don't match any tuple-union @return case
missing-return	Function missing return statement
undefined-global	Reference to unresolved global name
undefined-field	Reading a nonexistent field on a @class, a module-private table (local p = {}), or a string value (("x").foo, checked against the string library)
need-check-nil	Field/method access on possibly-nil value (off by default)
nil-index	Bracket-indexing a table with a possibly-nil key (off by default)
nil-table-key	Table key type annotation includes nil (table<string?, V>)
access-private	Accessing @field private from outside
access-protected	Accessing @field protected from outside hierarchy (also _-prefixed fields when implicitProtectedPrefix is enabled)
duplicate-index	Duplicate keys in table constructors
redundant-value	Extra values in assignments
unbalanced-assignments	More variables than values in assignments, including when a function call returns fewer values than variables assigned
missing-fields	Missing required fields when constructing @class tables
undefined-doc-class	Undefined class name in @class Foo: Parent
undefined-doc-name	Undefined type name in annotations
undefined-doc-param	@param name not matching function parameters
duplicate-doc-param	Duplicate @param annotations
duplicate-doc-field	Duplicate @field annotations
duplicate-doc-alias	Duplicate @alias declarations
doc-field-no-class	@field on a non-@class table
doc-func-no-function	Function-level annotation (@param, @return, etc.) not attached to a function definition
circle-doc-class	Circular @class inheritance chains
malformed-annotation	Unknown or incomplete ---@ annotations
multi-return-projection	returns<F> discards extra return values from F
builds-field-not-self	@builds-field method uses @return ClassName instead of @return self
unknown-diag-code	Unknown code in @diagnostic directives
unknown-cast-variable	@cast of a variable that isn't in scope
duplicate-constructor	Multiple @constructor on a single class
constructor-return	@constructor with return other than @return self
count-down-loop	For-loop step direction doesn't match start/end
wrong-flavor-api	API not available in all declared flavors
secret-arithmetic	Arithmetic on a value that may be secret (retail)
secret-comparison	Comparing a value that may be secret, including as a numeric for bound (retail)
secret-condition	Testing a boolean that may be secret in a condition or and/or (retail)
secret-table-key	Using a value that may be secret as a table key (retail)
secret-argument	Passing a value that may be secret to an API that rejects secrets from addon code (retail)
secret-access	Indexing (including a method call), calling, or taking the length of a value that may be secret (retail)
redundant-class-generic	Method redeclares class-level @generic
cannot-call	Calling a value whose type is not callable
invalid-op	Arithmetic, concatenation, or </>/<=/>= applied to incompatible types (e.g. + on strings instead of ..), or # on a value that has no length (off by default)
create-global	Implicit global creation
invalid-class-parent	Inheriting from a non-table type (number, string, literals, etc.)
mixed-enum-values	@enum with mixed number/string values or unsupported value types
unknown-callback-event	Event name passed to a callback registry that was never declared via GenerateCallbackEvents (off by default)
class-shadows-builtin	A workspace @class with its own @fields reuses a built-in WoW API class name
redefined-local	Same-scope local variable redefinition
duplicate-set-field	Setting an already-set field on @class tables

Hint severity

Code	Description
return-self-class-name	Method uses @return ClassName instead of @return self
unused-local	Unreferenced local variables (an unused local function reports unused-function instead, which is off by default)
unused-function	Unused function definitions, including local function f() and local f = function() end (off by default)
unused-vararg	Function declares ... but never uses it (off by default)
shadowed-local	Local variable shadows an outer-scope variable
inject-field	Setting undeclared fields on @class tables
unreachable-code	Code after return
code-after-break	Code after break
incomplete-signature-doc	Partial @param/@return annotations (off by default)
missing-param-annotation	Non-file-local function parameter has no @param (off by default)
missing-return-annotation	Non-file-local function returns a value but has no @return (off by default)
empty-block	Empty control flow body
redundant-return	Bare return at end of function
trailing-space	Line ends with whitespace
not-precedence	not x <cmp> y is (not x) <cmp> y
redundant-or	or where left side is always truthy (RHS is dead code) (off by default)
redundant-and	and where left side is always falsy (RHS is dead code) or always truthy (operator is a no-op) (off by default)
redundant-condition	if/elseif/while condition is provably constant (off by default)
implicit-nil-return	Bare return in function with optional @return (off by default)
unknown-param-type	Parameter has an unknown or any type (off by default)
unknown-return-type	Returned value has an unknown or any type (off by default)
unknown-local-type	Local, for, or global variable has an unknown or any type (off by default)
unknown-field-type	Class field has an unknown or any type (off by default)

missing-param-annotation / missing-return-annotation

Flag functions that lack @param / @return documentation. Both are off by default. Enable them when you want every public function fully documented:

{
  "diagnostics": {
    "enable": ["missing-param-annotation", "missing-return-annotation"]
  }
}

missing-param-annotation fires once per source parameter without a matching @param (the implicit self of a colon method and the conventional _ throwaway are skipped). missing-return-annotation fires once on a function whose body returns a value but has no @return.

Scope: only functions reachable beyond their file are checked. Checked:

• ✅ Global functions: function GlobalFn() end
• ✅ Methods/fields on a global table: function GlobalApi.Run() end
• ✅ Methods/fields on a @class: function Widget:SetValue() end
• ✅ Methods/fields on the addon namespace: function ns.Module.Process() end
• ✅ Methods on a local table that is attached to the addon namespace (local M = {}; function M.foo() end; ns.M = M)

Skipped:

• ❌ local function definitions
• ❌ Anonymous function literals (local f = function() … end, callback arguments)
• ❌ Bare function foo() that reassigns a forward-declared local foo
• ❌ Methods on a file-private local table (local cache = {}; function cache.get() end) that never escapes the file

The escape test for table methods reuses the workspace global scan: a method is "reachable" exactly when the language server registers it as a cross-file symbol, so this stays consistent with go-to-definition and find-references.

This differs from incomplete-signature-doc, which fires only when a signature is partially annotated (and regardless of where the function lives). missing-*-annotation fires even on a completely undocumented function, but only for non-file-local ones. The two can be enabled together; a partially-annotated global will then report under both.

redundant-condition

Flags if/elseif/while/repeat...until conditions that are provably always true or always false. Detected patterns:

• Always-truthy/falsy type: the condition's resolved type is guaranteed truthy (e.g. table, number) or guaranteed falsy (nil).
• Negation of a constant: not expr where expr is itself always truthy or always falsy (e.g. if not tbl where tbl is a table).
• Type-incompatible equality: ==/~= between values whose types can never match at runtime (e.g. num == "hello", nonNilVar == nil).
• Literal-union miss: x == "c" where x is typed as "a"|"b" and "c" is not a member.
• Two-literal comparison: both sides are concrete literals (e.g. 1 == 2, "a" == "a", 3 < 2).
• Self-comparison: x < x or x > x (always false; NaN-safe). <=/>=/==/~= self-comparisons are excluded because NaN breaks them.
• Redundant type() guard: type(x) == "number" where x is already known to be a number (always true) or can never be a number (always false).

Loop idioms (while true, repeat...until false) are not flagged. Conditions referencing variables reassigned inside loops are suppressed to avoid false positives.

unused-function

Flags function definitions that are never referenced anywhere in the workspace. Covers top-level global functions, methods defined on tables (e.g. function NS.Method()), and local functions. An unused local function f() reports unused-function, not unused-local.

What counts as "used":

• Called anywhere in the workspace, including self:Method() calls
• Referenced as a value (e.g. passed as a callback, stored in a variable or table)
• Named by a string where the API takes a method name, such as self:ScheduleTimer("OnTick", 1) (parameters typed keyof T)

What is skipped (not flagged):

• Functions whose name starts with _ (convention for intentionally unused)
• Functions defined in library files (directories marked with library in .wowluarc.json)
• Interface methods: if 2+ distinct tables define a method taking self (function T:Method() or function T.Method(self)) with the same name, those methods are treated as a framework callback pattern (duck-typing dispatch). This also covers a method and its override in a subclass. Static functions such as function Module.Reset() are always checked and don't count toward the 2.

Cross-file behavior:

This diagnostic requires a multi-file workspace scan. It compares definitions from all files against references from all files. In single-file mode (e.g. evaluate), only per-file unused functions are detected.

TOC file diagnostics

These diagnostics apply to .toc files only. See the TOC Files guide for details.

Code	Severity	Description
toc-missing-interface	Warning	Required ## Interface: field is missing
toc-duplicate-header	Warning	Same header key appears more than once
toc-unknown-header	Hint	Header not in the known catalog and not an X-* custom field
toc-invalid-interface	Error	Interface value is not a valid numeric version
toc-nonexistent-file	Warning	Referenced file does not exist on disk
toc-invalid-value	Warning	Unknown game type in AllowLoadGameType / ExcludeLoadGameType (header or per-line), or a header missing its colon

LuaLS compatibility aliases

Alias	Maps to
invisible	access-private, access-protected
param-type-mismatch	type-mismatch
return-type-mismatch	return-mismatch

Diagnostic codes that LuaLS defines but wowlua_ls has no equivalent for (e.g. lowercase-global, cast-type-mismatch, unused-label) are accepted silently in ---@diagnostic directives - they suppress nothing here, but won't trip unknown-diag-code, so a project that also runs LuaLS can keep its suppressions without noise.