Diagnostics

Triggered when there is an ambiguous statement that may need some brackets in order to correct the order of operations.

Triggers when a for loop will never reach its max/limit because it is incrementing when it should be decrementing.

for i=10, 1 do end

Triggered when a file is required under two different names. This can happen when requiring a file in two different directories:

📦 myProject/
    ├── 📂 helpers/
    │   ├── 📜 strings.lua
    │   └── 📜 pretty.lua
    └── 📜 main.lua

-- main.lua
local strings = require("helpers.strings")
local pretty = require("helpers.pretty")

-- helpers/pretty.lua
local strings = require("strings")

Triggered when calling a function across two lines from within a table. This may be unwanted and you may want to separate the fields with a comma (,) or semicolon (;) - unless you want to call the first field as a function.

local myTable = {
  myFunc
  ("param")
}

Triggered when calling a function from the next line. This may be unintended and you may want to add a semicolon ; to end the line.

print(1)
('x'):sub(1, 2)

Default File Status: "None"

Triggered when calling an asynchronous function from within a synchronous function.

Default File Status: "None"

Triggered when attempting to call coroutine.yield() when it is not permitted.

Default File Status: "None"

Triggered when the opinionated style checking detects an incorrectly styled line.

Default File Status: "None"

Triggered when the opinionated style checking detects an incorrectly named element.

Default File Status: "None"

Triggered when an element is not declared local to avoid accidentally global elements.

Triggered when there are duplicate indices.

local t = {
    -- triggered by indexes
    [1] = "a",
    [1] = "b",

    -- triggered by keys as well
    two = "c",
    two = "d"
}

Triggered when setting the same field in a class more than once. Check the names of your fields.

---@class myClass
local myTable = {}

function myTable:x() end

function myTable:x() end

Triggered when a global variable is defined and the environment (_ENV) is nil.

_ENV = nil

myGlobalVar = true

Triggered when referencing an undefined global (assumed to be global). The typical "does not exist" warning. Double check that you have spelled things correctly and that the variable exists.

Triggered when casting a variable to a type that does not match its initial type.

---@type boolean
local e = nil

---@cast e integer

Triggered when two classes inherit each other forming a never ending loop of inheritance.

---@class Car:Vehicle

---@class Vehicle:Car

Triggered when a @field is specified for a non-existent @class.

Triggered when there are two @alias annotations with matching names.

Triggered when there are two @field annotations with matching key values.

Triggered when there are two @param annotations with matching names.

Default File Status: "None"

Triggered when a functions signature is partially documented with annotations, but the annotations do not cover every element of the signature. E.g. one of the parameters is not annotated, or the return value is not annotated.

Default File Status: "None"

Triggered when a global function is not documented with annotations, but has parameters (requiring @param annotations) or a return value (requiring @return annotations). This ensures that functions are annotated when they are accessible outside of the current module.

Default File Status: "None"

Triggered when a local function is exported by adding it to the modules' return value, but the functions signature is not documented with annotations. This ensures that functions are annotated when they are accessible outside of the current module.

Triggered when referencing an undefined class in a @class annotation.

Triggered when referencing an undefined type or @alias in a @type annotation.

Triggered when referencing an undefined parameter from a function declartion.

---@param doesNotExist number
function subtract(a, b) end

Triggered when attempting to cast an undefined variable. Double check that you have spelled things correctly and that the variable exists. Appears when using @cast.

Triggered when entering an invalid diagnostic code. A diagnostic code is like one of the many diagnosis codes found on this page.

---@diagnostic disable: doesNotExist

Triggered when an unknown operator is found like **.

Triggered when attempting to close a variable with a non-object. The value of the variable must be an object with the __close metamethod (a Lua 5.4 feature).

local x <close> = 1

Triggered when a variable has been marked as deprecated yet is still being used. The variable in question will also be struck through.

Triggered when the returns of a function are being ignored when it is not permitted. Functions can specify that their returns cannot be ignored with @nodiscard.

Default File Status: "None"

Triggered when a variable has an unknown type that cannot be inferred. Useful for more strict typing.

Triggered when assigning a value, in which its type does not match the type of the variable it is being assigned to.

The below will trigger this diagnostic because we are assigning a boolean to a number:

---@type number
local isNum = false

Triggered when a local variable is being cast to a different value than it was defined as.

---@type boolean
local myBool

myBool = {}

Triggered when casting a variable to a type that does not match its initial type.

---@type boolean
local e = nil

---@cast e integer

Triggered when injecting an undefined field into a class instance. This can be solved by adding the @field to the class or by using @class directly on the instance.

---@class Car
---@field topSpeed number
---@field seats integer

---@type Car
local myCar = { topSpeed = 180, seats = 5 }

-- wheels was not defined in the Car class
-- because myCar was marked an instance of Car outside the definition of the Car class, its fields are strictly enforced
myCar.wheels = 6

Triggered when indexing a possibly nil object. Serves as a reminder to confirm the object is not nil before indexing - which would throw an error on execution.

---@class Bicycle
---@field move function

---@type Bicycle|nil
local bicycle

-- need to make sure bicycle isn't nil first
bicycle.move()

Triggered when the type of the provided parameter does not match the type requested by the function definition. Uses information defined with @param.

Triggered when the provided return value is not of the same type that the function expected.

---@return number sum
function add(a, b)
    return false
end

Triggered when referencing an undefined field.

---@class myClass
local myClass = {}

-- undefined field "hello"
myClass.hello()

Triggered when an instance of a class is missing a required @field.

Triggered when a required parameter is not supplied when calling a function. Uses information defined with @param.

Triggered when a required return is not supplied from within a function. Uses information defined with @return.

Triggered when a return is specified but the return value is not. Uses information defined with @return.

Triggered when providing an extra parameter that a function does not ask for. Uses information defined with @param.

Triggered when a return is returning an extra value that the function has not requested. Uses information defined with @return.

Triggered when providing an extra value to an assignment operation that will go unused.

local a, b = 1, 2, 3

Triggered when there are more variables being assigned than values to assign them.

local a, b, c = 1, 2