pcall versus xpcall for deployment error visibility

Answer

Use xpcall with a simple, non‑throwing error handler that calls debug.traceback. This provides a usable stack trace for deployment diagnostics across Lua 5.1 through 5.5, whereas pcall only returns the error message and adds no trace context.

Why this works (confirmed facts)

• pcall returns true, result on success or false, errMsg on failure; the second value is just the error object, which already contains whatever file/line info the error carried.
• xpcall invokes a user‑supplied handler; the handler can safely call debug.traceback(err, 2) to prepend a traceback that includes the call site and any active frames (subject to tail‑call optimisation).
• The handler must not raise its own error; if it does, the original error is lost. Keeping the handler pure (e.g., just returning a traceback) guarantees preservation of the original context.
• Lua 5.4’s debug.getupvalue/debug.setupvalue are not needed for basic trace fidelity; they only add variable inspection.
• Module caching via require does not store a failed module (the entry stays nil), so a retry will re‑execute the loader. However, any side effects that occurred before the error persist.
• Tail‑call optimisation can drop intermediate frames, reducing traceback granularity, but the traceback still shows the point where the error was raised, which is sufficient for most deployment diagnostics.

Steps to obtain reliable diagnostics

1. Wrap the module load or initialization in xpcall:

local ok, errOrTrace = xpcall(function()
    return require('my_module')  -- or any init code
end, function(err)
    -- Simple, non‑throwing handler: return a traceback
    return debug.traceback(err, 2)
end)

2. Check ok. If false, errOrTrace contains the error message followed by a stack trace suitable for logging.
3. If you need to retry a deployment after a failure, ensure the module’s loader is idempotent or clear the cache explicitly:

package.loaded['my_module'] = nil  -- forces a fresh require on retry

4. Log the trace (e.g., to a file or monitoring system) and proceed with your deployment roll‑out logic.

When the recommendation could change

If you discover that your Lua build disables debug.traceback (a highly atypical, stripped‑down interpreter), then xpcall would yield no extra context and you would need to rely on pcall plus manual error enrichment. Verify the presence of the debug library before finalising the approach.