Skip to main content
Control diagnostic warnings and errors for specific code sections, allowing you to selectively disable or enable analyzer checks.

​
Syntax

---@diagnostic <action>: <diagnostic_name>[, <diagnostic_name>...]

​
Actions

  • disable - Disable diagnostics for the following code
  • disable-next-line - Disable diagnostics for the next line only
  • disable-line - Disable diagnostics for the current line
  • enable - Re-enable previously disabled diagnostics

​
Common Diagnostic Names

  • undefined-global - Undefined global variable
  • lowercase-global - Global variable should be uppercase
  • unused-local - Unused local variable
  • unused-function - Unused function
  • param-type-mismatch - Parameter type mismatch
  • return-type-mismatch - Return type mismatch
  • undefined-field - Undefined field access
  • missing-return - Missing return statement
  • redundant-parameter - Redundant function parameter
  • deprecated - Usage of deprecated symbol

​
Examples

​
Disable Specific Warning

-- Disable specific warning for next line
---@diagnostic disable-next-line: undefined-global
print(someUndefinedVariable)

​
Disable Multiple Warnings

---@diagnostic disable-next-line: undefined-global, lowercase-global
GLOBAL_CONSTANT = someUndefinedValue

​
Unused Variable Warning

---@diagnostic disable-next-line: unused-local
local unusedVariable = "this won't be used"

​
Type Mismatch Warning

---@param value string
function processString(value)
    ---@diagnostic disable-next-line: param-type-mismatch
    processString(123)  -- Passing number instead of string
end

​
Undefined Field Warning

---@class User
---@field name string
local user = {}

---@diagnostic disable-next-line: undefined-field
local email = user.email  -- email field not defined in User class

​
Missing Return Warning

---@return string
function getName()
    ---@diagnostic disable-next-line: missing-return
    -- Function doesn't return anything but should return string
end

​
Deprecated Usage Warning

---@deprecated Use newFunction instead
function oldFunction()
    return "old implementation"
end

---@diagnostic disable-next-line: deprecated
local result = oldFunction()

​
Block-Level Control

do
    ---@diagnostic disable: undefined-global
    someGlobalVar = "this is OK"
    anotherGlobalVar = 42
    ---@diagnostic enable: undefined-global
end

​
File-Level Control

Place at the top of the file: 
---@diagnostic disable: lowercase-global

GLOBAL_CONFIG = {
    debug = true,
    version = "1.0.0"
}

​
Dynamic Code

---@diagnostic disable-next-line: undefined-field
local dynamicField = obj[computedFieldName]

​
Metatable Operations

local mt = {
    __index = function(t, k)
        ---@diagnostic disable-next-line: undefined-field
        return rawget(t, k) or defaultValue
    end
}

​
External Library Usage

---@diagnostic disable-next-line: undefined-global
local json = require("external-json-lib")

​
Multiple Lines

---@diagnostic disable: unused-local
local temp1 = getValue1()
local temp2 = getValue2()
local temp3 = getValue3()
---@diagnostic enable: unused-local

-- Continue with rest of code

​
Use Cases

​
Working with Dynamic APIs

When working with dynamic APIs that the analyzer can’t fully understand: 
---@diagnostic disable-next-line: undefined-field
local value = dynamicObject[computedKey]

​
Legacy Code Integration

When integrating with legacy code that doesn’t follow strict typing: 
---@diagnostic disable: param-type-mismatch
legacyFunction(anyValue)
---@diagnostic enable: param-type-mismatch

​
Intentional Patterns

When using intentional patterns that trigger warnings: 
---@diagnostic disable-next-line: redundant-parameter
string.format("%s", value, extraDebugInfo)  -- Extra param for debugging
Use diagnostic controls sparingly. Excessive use may hide real issues in your code. Always consider fixing the underlying issue first.
For file-level diagnostics that should apply to multiple files, consider using workspace configuration instead of per-file annotations.

​
Features

Selective Control

Enable or disable specific diagnostics

Scoped Disabling

Control diagnostics at line or block level

Multiple Diagnostics

Handle multiple diagnostic types at once

Fine-Grained

Precise control over analyzer behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us