debug.problems

Surface the recent errors and warnings the caller has not read yet.

debug.problems()

Non-crashing failures — a contract violation, a component awake/update throw, a component auto-disabled after erroring, an unresolved require, a bridged renderer or asset error — land in the engine's log ring but do not surface in execute results unless you happened to ask for them at the right level in the call where they occurred. debug.problems reads them back out.

When something you built does not behave, call this first. The engine has usually already logged the reason.

Each call advances a read-cursor and returns the problems logged since the previous call, oldest first — so the root-cause error (the awake() throw that disabled a component) reads ahead of the cascade it triggered. Repeated calls report only what is new.

debug.problems({
  level = "warn",   -- minimum severity: "warn" (default) or "error"
  limit = 50,       -- cap on entries returned (default 50)
  all   = false,    -- true: recent problems regardless of the cursor, cursor untouched
  peek  = false,    -- true: read the next batch without advancing the cursor
})

Returns:

{
  problems = {                     -- oldest first
    { seq, level, type, message, timestamp },
    ...
  },
  shown     = number,              -- #problems
  truncated = boolean,             -- more unread problems remain past `limit`
  cursor    = number,              -- read-cursor after this call
  counts    = { errors, warnings }, -- lifetime totals (survive ring eviction)
}

all = true gives a one-shot overview of the most recent problems without disturbing the drain cursor. peek = true previews the next batch and leaves it unread for the next call.

The full log ring — every level, searchable, countable, filterable by the script or entity that logged a line — is the logs toolbox, whose search, tail, errors and summary tools read it. Reach for those when you need more than the unread problems: a specific message, a specific entity, a specific minute, or the lines that led up to a failure. The same ring is also readable directly from Luau through the logs global, and as plain files at /zero/runtime/logs/engine, /zero/runtime/logs/errors and /zero/runtime/logs/script when a grep for a message you can name is shorter than a query.

This tool is the read-cursor view over the warn/error slice of it.