The `debug` library is not available in Lua filters

Open
#1,012 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
1-2 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
lua, rust
Domain
backend

Research direction

Start in crates/pampa/src/lua/filter.rs: inspect the filter environment setup around Lua::new() (lines 177–192) and the chunk name setup (lines 383–386). Reproduce with the supplied filter.lua and index.qmd using q2 render index.qmd --to html; compare with Quarto 1 if useful. Done when the filter can use debug.getinfo to obtain its running chunk path without dropping a path character.

Written by the indexing model from the issue text.

Description

Bug description

The global debug is nil in a Lua filter, so a call to debug.getinfo stops the render.

Extensions use this call to find the directory of the module that is running.
For example, a load_sibling helper that several of my extensions vendor reads debug.getinfo(1, "S").source, then loads a neighbouring file with require.
Three of the 40 extensions (all mine) I tested call debug.getinfo in their Lua files.
Quarto 1 runs Lua through Pandoc, which exposes the full debug library.

This is the Quarto 1 way of doing it, and a better way might be worth exploring in q2.
Both engines already cover the common cases without debug, which I checked on q2 and on Quarto 1.12.0:

  • A relative require("./b") in a nested module loads the neighbouring b.lua.
  • PANDOC_SCRIPT_FILE gives the path of the filter script.
  • quarto.utils.resolve_path resolves a path against the filter directory.

None of them gives a module its own path, and extensions that call debug.getinfo break today.

The filter environment uses Lua::new(), which skips debug as unsafe, although the comment says native builds load everything:

https://github.com/quarto-dev/q2/blob/a2a1cb948b1aec42c93200b880dc73567160f691/crates/pampa/src/lua/filter.rs#L177-L192

The chunk name of the filter script is set without a leading @, so once debug is loaded, source:sub(2) would still drop the first character of the path:

https://github.com/quarto-dev/q2/blob/a2a1cb948b1aec42c93200b880dc73567160f691/crates/pampa/src/lua/filter.rs#L383-L386

Steps to reproduce

filter.lua:

function Pandoc()
  return pandoc.Pandoc(pandoc.Para(pandoc.Str(debug.getinfo(1, "S").source)))
end

index.qmd:

---
filters:
  - filter.lua
---

x

Render it with q2 and with Quarto 1:

q2 render index.qmd --to html
quarto render index.qmd --to html
Actual behavior
Rendering single file: /private/tmp/q2-debug.Eqp8/index.qmd
error: while rendering /private/tmp/q2-debug.Eqp8/index.qmd
Error: Lua filter error: runtime error: [string "/private/tmp/q2-debug.Eqp8/filter.lua"]:2: attempt to index a nil value (global 'debug')
stack traceback:
    [string "/private/tmp/q2-debug.Eqp8/filter.lua"]:2: in function 'Pandoc'

1 error
Expected behavior

debug.getinfo(1, "S").source returns the path of the running chunk with a leading @, as in standard Lua.
Quarto 1 writes it into the page:

<p>@filter.lua</p>
Your environment
  • q2: Q2 (quarto 2) 0.40.0-nightly.20261101 (nightly built from a2a1cb9).
  • Quarto 1 for comparison: 1.12.0 (pre-release).
  • OS: macOS 27.2 (arm64).
  • Terminal, no IDE.
Dominant language
Rust
Stars
302
Forks
22
Avg merge
5h 2m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/q2

All issues in quarto-dev/q2

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.