> ## Documentation Index
> Fetch the complete documentation index at: https://gluals.arnux.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics

> GLuaLS checks your code for errors, type mismatches, unused variables, realm mistakes, and API misuse.

## 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:

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

```json .gluarc.json theme={null}
{
  "diagnostics": {
    "severity": {
      "unused": "hint",
      "undefined-field": "information",
      "param-type-mismatch": "warning"
    },
    "disable": ["redundant-return-value"],
    "enables": ["missing-return", "return-type-mismatch"]
  }
}
```

<Tip>
  Use the [interactive settings panel](/configuration/overview#settings-panel-recommended) to toggle diagnostics and change severity with checkboxes and dropdowns. You do not need to edit JSON.
</Tip>

***

## 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](/annotations/guard-metadata) for custom wrappers.

### 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](/language/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:

```lua theme={null}
-- 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](/annotations/diagnostic) 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:

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

```json .gluarc.json theme={null}
{
  "diagnostics": {
    "globals": ["MyFramework", "PLUGIN_REGISTRY"],
    "globalsRegex": ["^LIB_.*"]
  }
}
```