Diagnostics

Overview

Diagnostics appear as squiggly underlines in the editor and in the Problems panel (Ctrl+Shift+M). Each diagnostic has a severity level and a code identifier you can use for configuration.

Severity levels

Severity	Appearance	When to use
`error`	Red underline	Hard errors that will likely break your code
`warning`	Yellow underline	Probable bugs or type mismatches
`information`	Blue underline	Stylistic or best-practice suggestions
`hint`	Subtle underline	Minor suggestions, safe to ignore

Configuring diagnostic severity

Change the severity of any diagnostic code, or disable it:

Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.

.gluarc.json

{
  "diagnostics": {
    "severity": {
      "unused": "hint",
      "undefined-field": "information",
      "param-type-mismatch": "warning"
    },
    "disable": ["redundant-return-value"],
    "enables": ["missing-return", "return-type-mismatch"]
  }
}

Use the interactive settings panel to toggle diagnostics and change severity with checkboxes and dropdowns. You do not need to edit JSON.

Diagnostic reference

Type checking

Code	Default	Description
`syntax-error`	Error	Lua syntax is invalid
`param-type-mismatch`	Warning	Argument type doesn’t match the expected parameter type
`missing-parameter`	Warning	Required parameter not provided
`redundant-parameter`	Information	Extra argument passed beyond what the function accepts
`assign-type-mismatch`	Hint	Assigned value type doesn’t match the variable type
`return-type-mismatch`	Off	Return type doesn’t match the declared return type
`missing-return-value`	Warning	Function declared to return a value but doesn’t in all paths
`redundant-return-value`	Off	Extra return value beyond what the function declares
`missing-return`	Off	Function should return a value but doesn’t
`cast-type-mismatch`	Warning	Cast type is incompatible with the actual type
`need-check-nil`	Hint	Value may be nil; you should check before using it
`unchecked-nil-access`	Warning	Chained access or call through an opaque table member that may be nil
`infer-unknown`	Hint	An otherwise unknown value was stabilized from usage context and may be incorrect
`infer-unguarded-child`	Warning	A child value was inferred from an unguarded parent relationship and may be incorrect
`undefined-field`	Warning	Field doesn’t exist on the type
`undefined-method`	Error	Method called with `:` doesn’t exist on the type or an inferred child type
`missing-fields`	Warning	Table literal is missing required fields
`undefined-global`	Error	Referenced variable is not defined globally or locally
`undefined-global-assignment`	Warning	Undefined global used as a function argument or assigned to a variable / table field (alias: `undefined-global-argument`)
`type-not-found`	Warning	A referenced type name doesn’t exist
`generic-constraint-mismatch`	Information	Generic type argument violates a constraint
`enum-value-mismatch`	Warning	Value doesn’t match a known enum entry
`call-non-callable`	Off	Code tries to call a value that is not a function
`require-module-not-visible`	Warning	Required module is not visible from this file

need-check-nil and unchecked-nil-access understand validity guards such as IsValid and annotated guard wrappers. See Guard metadata for custom wrappers. missing-fields and missing-parameter skip anything with a documented default. Write ---@field clipSize number = 30 or ---@param times number = 1 when a base class, a setup function, or the function itself fills the value in. See @field and @param.

Code quality

Code	Default	Description
`unused`	Hint	Local variable or function is never used
`unused-self`	Off	`self` parameter is never used in a method
`unreachable-code`	Hint	Code after a `return` or `error()` cannot execute
`deprecated`	Hint	Using a deprecated function or field
`duplicate-require`	Hint	Module is `require()`d more than once in the same scope
`redefined-local`	Hint	Local variable shadows an outer local with the same name
`redefined-label`	Warning	Code defines the same goto label more than once
`duplicate-index`	Warning	Table literal has the same key more than once
`duplicate-set-field`	Off	Code assigns a field more than once
`duplicate-type`	Off	Code declares the same type name in multiple places
`unbalanced-assignments`	Warning	Left-hand and right-hand sides of an assignment have different counts
`local-const-reassign`	Error	Code reassigns a `<const>` local
`read-only`	Warning	Code writes to a value declared as read-only
`iter-variable-reassign`	Off in LuaJIT	Code reassigns a loop variable in a Lua version where it is constant
`preferred-local-alias`	Hint	A local alias is preferred for this value
`await-in-sync`	Warning	`await` is used in a function that is not asynchronous
`code-style-check`	Off	Code does not match the configured style rules
`non-literal-expressions-in-assert`	Off	An assertion uses an expression that is hard to report clearly
`unnecessary-assert`	Off	An assertion is not needed
`unnecessary-if`	Off	An `if` statement can be simplified
`invert-if`	Off	Inverting an `if` statement would simplify the code

Documentation

Code	Default	Description
`annotation-usage-error`	Error	Annotation has wrong syntax or appears in the wrong context
`doc-syntax-error`	Error	Annotation comment has a syntax error
`undefined-doc-param`	Warning	Documentation names a parameter that the function does not have
`duplicate-doc-field`	Warning	`@class` documents the same field more than once
`incomplete-signature-doc`	Off	Function lacks parameter or return documentation
`missing-global-doc`	Off	Global function or variable lacks documentation
`unknown-doc-tag`	Off	Unknown `@tag` in an annotation comment
`inject-field`	Off	Code adds a field to a type outside its class definition
`circle-doc-class`	Warning	Documented classes form an inheritance loop
`attribute-param-type-mismatch`	Warning	Annotation attribute argument has the wrong type
`attribute-missing-parameter`	Warning	Annotation attribute is missing an argument
`attribute-redundant-parameter`	Warning	Annotation attribute has an extra argument
`global-in-non-module`	Off	A file that is not a module defines a global

Access control

Code	Default	Description
`access-invisible`	Warning	Accessing a `private` or `protected` member outside its class
`discard-returns`	Warning	Code ignores the return value from a `@nodiscard` function

Garry’s Mod Lua

Network checks also work through aliases and wrappers around the standard GMod network functions. See Network analysis for examples and settings.

Code	Default	Description
`gmod-realm-mismatch`	Error	Calling a realm-specific function from the wrong realm
`gmod-realm-mismatch-heuristic`	Error	Likely realm mismatch based on inferred evidence
`gmod-unknown-realm`	Hint	Realm could not be resolved for a realm-aware call
`gmod-invalid-hook-name`	Warning	Hook name does not match a recognized GMod hook
`gmod-unknown-net-message`	Warning	`net.Start(name)` uses an unregistered message name
`gmod-net-missing-network-counterpart`	Warning	`net.Start` lacks a matching `net.Receive` in the expected opposite realm
`gmod-net-read-write-order-mismatch`	Warning	`net.Read` calls don’t match the order of `net.Write` calls
`gmod-net-read-write-type-mismatch`	Warning	`net.Read` type doesn’t match the corresponding `net.Write`
`gmod-net-read-write-bits-mismatch`	Warning	Literal bit-width differs between a matched write/read pair
`gmod-duplicate-system-registration`	Hint	Duplicate registration (concommand, net, timer, etc.)
`gmod-null-check`	Warning	Entity validity is checked with truthiness or `nil` instead of `IsValid`

Suppressing individual diagnostics

Use ---@diagnostic annotations to suppress warnings for specific lines or blocks:

-- Suppress for the next line only
---@diagnostic disable-next-line: undefined-global
print(someExternalGlobal)

-- Suppress for the current line
print(x) ---@diagnostic disable-line: undefined-global

-- Suppress for an entire block
---@diagnostic disable: undefined-global
SOME_GLOBAL = "value"
ANOTHER_GLOBAL = 42
---@diagnostic enable: undefined-global

See the @diagnostic annotation reference for full details.

Global whitelist

Add globals that your code uses but GLuaLS does not know about, such as globals from a module loaded by another file:

Use the settings menu instead of editing the JSON file directly. This helps you avoid config mistakes.

.gluarc.json

{
  "diagnostics": {
    "globals": ["MyFramework", "PLUGIN_REGISTRY"],
    "globalsRegex": ["^LIB_.*"]
  }
}

Overview

Code intelligence

Garry's Mod

Classes

Debugger

AI integration

Overview

Severity levels

Configuring diagnostic severity

Diagnostic reference

Type checking

Code quality

Documentation

Access control

Garry’s Mod Lua

Suppressing individual diagnostics

Global whitelist

​Overview

​Severity levels

​Configuring diagnostic severity

​Diagnostic reference

​Type checking

​Code quality

​Documentation

​Access control

​Garry’s Mod Lua

​Suppressing individual diagnostics

​Global whitelist

Overview

Severity levels

Configuring diagnostic severity

Diagnostic reference

Type checking

Code quality

Documentation

Access control

Garry’s Mod Lua

Suppressing individual diagnostics

Global whitelist