Skip to main content

debug

Library

Provides functions to collect and modify information of the Luau callstack and Luau functions.

Functions​

getupvaluecount​

</>
debug.getupvaluecount(
fnOrIndex: number | (T...) → U...--

The function or call-stack index to get the number of up-values.

) → number--

The number of up-values this function/ stack index holds.

Gets the number of up-values/ up-references of the given function or call-stack index fnOrIndex.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getconstantcount​

</>
debug.getconstantcount(
fnOrIndex: number | (T...) → U...--

The function or call-stack index to get the number of constants.

) → number--

The number of constants this function/ stack index holds.

Gets the number of constants of the luau function or call-stack index fnOrIndex.

C closures

C closures do not have constants.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getconstants​

</>
debug.getconstants(
fnOrIndex: number | (T...) → U...--

The function or call-stack index to get all constants.

) → {any}--

All constants this function/ stack index holds.

Gets all of the constants of the luau function or call-stack index fnOrIndex.

C closures

C closures do not have constants.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getconstant​

</>
debug.getconstant(
fnOrIndex: number | (T...) → U...,--

The function or call-stack index to get.

index: number--

The numerical index of the constant to get.

) → any--

The constant at the given index.

Gets the constant of the luau function or call-stack index fnOrIndex at the given constant index.

C closures

C closures do not have constants.

Errors

TypeDescription
invalid constant indexThe index must be non-negative, more than 0 and smaller than the number of constants the closure has. Use debug.getconstantcount to get the number of constants before calling this function.
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

setconstant​

</>
debug.setconstant(
fnOrIndex: number | (T...) → U...,--

The function or call-stack index to set.

index: number,--

The numerical index of the constant to set.

newValue: any--

The new constant to set.

) → ()

Sets the constant of the luau function or call-stack index fnOrIndex at the given constant index to newValue.

Vector objects

Luau can have Vector objects as constants. Due to this, you must set the extra field on the lua_TValue structure correctly!

C closures

C closures do not have constants.

Errors

TypeDescription
the type of the new value that of the originalWhatever is at index index does not match with the type of newValue. For userdatas, their tags must also match.
invalid constant indexThe index must be non-negative, more than 0 and smaller than the number of constants the closure has. Use debug.getconstantcount to get the number of constants before calling this function.
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getupvalues​

</>
debug.getupvalues(
fnOrIndex: number | (T...) → U...--

The function or call-stack index to get all up-values/ up-references.

) → {any}--

All up-values/up-reference this function/ stack index holds.

Gets all of the up-value/ up-references of the given function or call-stack index fnOrIndex.

C closures

You must NEVER allow the mutation of the up-values of C closures! C closures are specific on their constraints.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getupvalue​

</>
debug.getupvalue(
fnOrIndex: number | (T...) → U...,--

The function or call-stack index to get.

upIndex: number--

The numerical index of the up-reference/up-value to get.

) → any--

The up-reference/up-value at the given index.

Gets the up-value or up-reference of the given function or call-stack index fnOrIndex at the given up-reference/up-value index.

C closures

You must NEVER allow the mutation of the up-values of C closures! C closures are specific on their constraints.

Errors

TypeDescription
invalid upvalue indexThe index must be non-negative, more than 0 and smaller than the number of upvalues the closure has. Use debug.getupvaluecount to get the number of upvalues before calling this function.
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

setupvalue​

</>
debug.setupvalue(
fnOrIndex: number | (T...) → U...,--

The function or call-stack index to set.

upIndex: number,--

The numerical index of the up-reference/up-value to set.

newValue: any--

The new up-reference/up-value to set.

) → ()

Sets the up-value or up-reference of the given function or call-stack index fnOrIndex at the given up-reference/up-value index to value.

C closures

You must NEVER allow the mutation of the up-values of C closures! C closures are specific on their constraints.

Errors

TypeDescription
the type of the new value that of the originalWhatever is at index upIndex does not match with the type of newValue. For userdatas, their tags must also match.
invalid upvalue indexThe index must be non-negative, more than 0 and smaller than the number of upvalues the closure has. Use debug.getupvaluecount to get the number of upvalues before calling this function.
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

setstack​

</>
debug.setstack(
level: number,--

The level to set.

stackIndex: number,--

The numerical index in the stack to set.

newStackElement: any--

The new stack element to set.

) → ()

Sets the stack element at index stackIndex at call-stack level level to newStackElement.

C closures

You must NEVER allow the mutation of the stacks of C closures! This is related to vulnerabilities.

Errors

TypeDescription
the type of the new value that of the originalWhatever is at element stackIndex does not match with the type of newStackElement. For userdatas, their tags must also match.
invalid stack indexThe index must be non-negative, more than 0 and smaller than the size of the stack. Use debug.getstackcount to get the number of upvalues before calling this function.
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getstack​

</>
debug.getstack(
level: number,--

The level to get.

stackIndex: number?--

The numerical index in the stack to get, or nil to get the entire stack.

) → any | {any}--

The stack element at the given index, or the entire stack.

Returns the stack element at index stackIndex at call-stack level level. If no stackIndex is provided, the entire stack will be returned.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

getstackcount​

</>
debug.getstackcount(
level: number--

The level to get.

) → number--

The number of elements on the luau stack.

Returns the number of elements on the luau stack at the provided call-stack level.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.

validlevel​

</>
debug.validlevel(
level: number--

The level to check.

) → boolean--

If true, the level is valid and can be used on call functions.

Returns if the given call-stack level is a valid level.

traceback​

</>
debug.traceback(
threadOrMessage: string | thread,--

The first line of the returned string.

levelOrMessage: number | string,--

The number of calls "up" the call stack to return.

level: number?
) → string--

The traceback up to the given level from the current function.

identical to debug.traceback

Function Behaviour

This function skips over C closures.

info​

</>
debug.info(
levelOrThreadOrFunction: number | thread | (T...) → U...,--

The level/ function to get the information from. Or, optionally, the thread to get the information from.

whatOrLevelOrFunction: number | string | (T...) → U...,--

The information to get, or the level/ function to get the information from.

what: string?--

The information to get (if the thread is provided as first argument).

) → K... | nil--

Information on the order of 'what', may be nil.

Identical to debug.info

getinfo​

</>
debug.getinfo(
level: number | (T...) → U...--

The level/ function to get the information from.

) → DebugInfo--

The information about the function that is currently using the given stack frame or of a given function.

Returns information about the function that is currently using the given stack frame or of a given function.

Errors

TypeDescription
level out of rangeThe provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function.
Show raw api
{
    "functions": [
        {
            "name": "getupvaluecount",
            "desc": "Gets the number of up-values/ up-references of the given function or call-stack index `fnOrIndex`.",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to get the number of up-values.",
                    "lua_type": "number | (T...) -> U..."
                }
            ],
            "returns": [
                {
                    "desc": "The number of up-values this function/ stack index holds.",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 17,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getconstantcount",
            "desc": "Gets the number of constants of the luau function or call-stack index `fnOrIndex`.\n\n\n:::warning C closures\nC closures do not have constants.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to get the number of constants.",
                    "lua_type": "number | (T...) -> U..."
                }
            ],
            "returns": [
                {
                    "desc": "The number of constants this function/ stack index holds.",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 33,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getconstants",
            "desc": "Gets all of the constants of the luau function or call-stack index `fnOrIndex`.\n\n\n:::warning C closures\nC closures do not have constants.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to get all constants.",
                    "lua_type": "number | (T...) -> U..."
                }
            ],
            "returns": [
                {
                    "desc": "All constants this function/ stack index holds.",
                    "lua_type": "{ any }"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 49,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getconstant",
            "desc": "Gets the constant of the luau function or call-stack index `fnOrIndex` at the given constant `index`.\n\n\n:::warning C closures\nC closures do not have constants.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to get.",
                    "lua_type": "number | (T...) -> U..."
                },
                {
                    "name": "index",
                    "desc": "The numerical index of the constant to get.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The constant at the given index.",
                    "lua_type": "any"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid constant index",
                    "desc": "The index must be non-negative, more than 0 and smaller than the number of constants the closure has. Use debug.getconstantcount to get the number of constants before calling this function."
                },
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 67,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "setconstant",
            "desc": "Sets the constant of the luau function or call-stack index `fnOrIndex` at the given constant `index` to `newValue`.\n\n\n:::warning Vector objects\nLuau can have Vector objects as constants. Due to this, you must set the `extra` field on the `lua_TValue` structure correctly!\n:::\n\n:::warning C closures\nC closures do not have constants.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to set.",
                    "lua_type": "number | (T...) -> U..."
                },
                {
                    "name": "index",
                    "desc": "The numerical index of the constant to set.",
                    "lua_type": "number"
                },
                {
                    "name": "newValue",
                    "desc": "The new constant to set.",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "the type of the new value that of the original",
                    "desc": "Whatever is at index index does not match with the type of newValue. For userdatas, their tags must also match."
                },
                {
                    "lua_type": "invalid constant index",
                    "desc": "The index must be non-negative, more than 0 and smaller than the number of constants the closure has. Use debug.getconstantcount to get the number of constants before calling this function."
                },
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 90,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getupvalues",
            "desc": "Gets all of the up-value/ up-references of the given function or call-stack index `fnOrIndex`.\n\n\n:::danger C closures\nYou must NEVER allow the mutation of the up-values of C closures! C closures are specific on their constraints.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to get all up-values/ up-references.",
                    "lua_type": "number | (T...) -> U..."
                }
            ],
            "returns": [
                {
                    "desc": "All up-values/up-reference this function/ stack index holds.",
                    "lua_type": "{ any }"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 104,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getupvalue",
            "desc": "Gets the up-value or up-reference of the given function or call-stack index `fnOrIndex` at the given up-reference/up-value `index`.\n\n\n:::danger C closures\nYou must NEVER allow the mutation of the up-values of C closures! C closures are specific on their constraints.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to get.",
                    "lua_type": "number | (T...) -> U..."
                },
                {
                    "name": "upIndex",
                    "desc": "The numerical index of the up-reference/up-value to get.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The up-reference/up-value at the given index.",
                    "lua_type": "any"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "invalid upvalue index",
                    "desc": "The index must be non-negative, more than 0 and smaller than the number of upvalues the closure has. Use debug.getupvaluecount to get the number of upvalues before calling this function."
                },
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 122,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "setupvalue",
            "desc": "Sets the up-value or up-reference of the given function or call-stack index `fnOrIndex` at the given up-reference/up-value `index` to `value`.\n\n\n:::danger C closures\nYou must NEVER allow the mutation of the up-values of C closures! C closures are specific on their constraints.\n:::",
            "params": [
                {
                    "name": "fnOrIndex",
                    "desc": "The function or call-stack index to set.",
                    "lua_type": "number | (T...) -> U..."
                },
                {
                    "name": "upIndex",
                    "desc": "The numerical index of the up-reference/up-value to set.",
                    "lua_type": "number"
                },
                {
                    "name": "newValue",
                    "desc": "The new up-reference/up-value to set.",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "the type of the new value that of the original",
                    "desc": "Whatever is at index upIndex does not match with the type of newValue. For userdatas, their tags must also match."
                },
                {
                    "lua_type": "invalid upvalue index",
                    "desc": "The index must be non-negative, more than 0 and smaller than the number of upvalues the closure has. Use debug.getupvaluecount to get the number of upvalues before calling this function."
                },
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 141,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "setstack",
            "desc": "Sets the stack element at index `stackIndex` at call-stack level `level` to `newStackElement`.\n\n\n:::danger C closures\nYou must NEVER allow the mutation of the stacks of C closures! This is related to vulnerabilities.\n:::",
            "params": [
                {
                    "name": "level",
                    "desc": "The level to set.",
                    "lua_type": "number"
                },
                {
                    "name": "stackIndex",
                    "desc": "The numerical index in the stack to set.",
                    "lua_type": "number"
                },
                {
                    "name": "newStackElement",
                    "desc": "The new stack element to set.",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "the type of the new value that of the original",
                    "desc": "Whatever is at element stackIndex does not match with the type of newStackElement. For userdatas, their tags must also match."
                },
                {
                    "lua_type": "invalid stack index",
                    "desc": "The index must be non-negative, more than 0 and smaller than the size of the stack. Use debug.getstackcount to get the number of upvalues before calling this function."
                },
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 159,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getstack",
            "desc": "Returns the stack element at index `stackIndex` at call-stack level `level`.\nIf no `stackIndex` is provided, the entire stack will be returned.",
            "params": [
                {
                    "name": "level",
                    "desc": "The level to get.",
                    "lua_type": "number"
                },
                {
                    "name": "stackIndex",
                    "desc": "The numerical index in the stack to get, or nil to get the entire stack.",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "The stack element at the given index, or the entire stack.",
                    "lua_type": "any | { any }"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 171,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getstackcount",
            "desc": "Returns the number of elements on the luau stack at the provided call-stack `level`.",
            "params": [
                {
                    "name": "level",
                    "desc": "The level to get.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The number of elements on the luau stack.",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 183,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "validlevel",
            "desc": "Returns if the given call-stack level is a valid level.",
            "params": [
                {
                    "name": "level",
                    "desc": "The level to check.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "If true, the level is valid and can be used on call functions.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 194,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "traceback",
            "desc": "identical to `debug.traceback`\n\n\n\n:::info Function Behaviour\nThis function skips over C closures.\n:::",
            "params": [
                {
                    "name": "threadOrMessage",
                    "desc": "The first line of the returned string.",
                    "lua_type": "string | thread"
                },
                {
                    "name": "levelOrMessage",
                    "desc": "The number of calls \"up\" the call stack to return.",
                    "lua_type": "number | string"
                },
                {
                    "name": "level",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "The traceback up to the given level from the current function.",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 212,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "info",
            "desc": "Identical to `debug.info`",
            "params": [
                {
                    "name": "levelOrThreadOrFunction",
                    "desc": "The level/ function to get the information from. Or, optionally, the thread to get the information from.",
                    "lua_type": "number | thread | (T...) -> U..."
                },
                {
                    "name": "whatOrLevelOrFunction",
                    "desc": "The information to get, or the level/ function to get the information from.",
                    "lua_type": "number | string | (T...) -> U..."
                },
                {
                    "name": "what",
                    "desc": "The information to get (if the thread is provided as first argument).",
                    "lua_type": "string?"
                }
            ],
            "returns": [
                {
                    "desc": "Information on the order of 'what', may be nil.",
                    "lua_type": "K... | nil"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 226,
                "path": "impl/Libraries/debug.luau"
            }
        },
        {
            "name": "getinfo",
            "desc": "Returns information about the function that is currently using the given stack frame or of a given function.",
            "params": [
                {
                    "name": "level",
                    "desc": "The level/ function to get the information from.",
                    "lua_type": "number | (T...) -> U..."
                }
            ],
            "returns": [
                {
                    "desc": "The information about the function that is currently using the given stack frame or of a given function.",
                    "lua_type": "DebugInfo"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "level out of range",
                    "desc": "The provided stack level was out of range. use debug.validlevel to check if the level is valid before calling this function."
                }
            ],
            "source": {
                "line": 241,
                "path": "impl/Libraries/debug.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "debug",
    "desc": "Provides functions to collect and modify information of the Luau callstack and Luau functions.",
    "tags": [
        "Library"
    ],
    "source": {
        "line": 7,
        "path": "impl/Libraries/debug.luau"
    }
}