PRQL/prql · error · anyhow::Error

unknown debug log format for file

Error message

unknown debug log format for file {path:?}

What it means

After compilation, `write_log` dispatches on the debug-log file extension: `json` and `html` are supported renderers; any other (or missing) extension hits this fallback error. It's a user-facing format validation error, not an internal bug.

Solutions

  1. Use a `.json` extension for raw log output
  2. Use an `.html` extension for a rendered trace view
  3. Rename the target file to one of the supported extensions and rerun

Example fix

// before
prqlc compile --debug-log trace.txt
// after
prqlc compile --debug-log trace.html
Defensive patterns

Strategy: validation

Validate before calling

const valid = (p: string) => /\.(json|html)$/i.test(p);

Type guard

function isDebugLogPath(p: string): p is `${string}.json` | `${string}.html` { return /\.(json|html)$/i.test(p); }

Try / catch

try { writeLog(path) } catch (e) { if (String(e).includes('unknown debug log format')) { writeLog(path.replace(/\.\w+$/, '.json')) } else { throw e } }

Prevention

When it happens

Trigger: Passing a debug log path whose extension is neither `.json` nor `.html` (e.g. `--debug-log out.txt`, `log`, `log.yaml`).

Common situations: Typo in the output filename; assuming any extension works; shell completion absent so users guess the format.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of PRQL/prql@e164e249b9 (2026-09-09). Data as JSON: /api/errors/adbae71dd92a947c. Report an issue: GitHub.

Appendix: source

Thrown at prqlc/prqlc/src/cli/mod.rs:596

pub fn write_log(path: &std::path::Path) -> Result<()> {
    let debug_log = if let Some(debug_log) = debug::log_finish() {
        debug_log
    } else {
        return Err(anyhow!(
            "debug log was started, but it cannot be found after compilation"
        ));
    };
    match path.extension().and_then(|s| s.to_str()) {
        Some("json") => {
            let file = BufWriter::new(File::create(path)?);
            serde_json::to_writer(file, &debug_log)?;
        }
        Some("html") => {
            let file = BufWriter::new(File::create(path)?);
            debug::render_log_to_html(file, &debug_log)?;
        }
        _ => {
            return Err(anyhow!("unknown debug log format for file {path:?}"));
        }
    }
    Ok(())
}

fn drop_module_def(stmts: &mut Vec<pr::Stmt>, name: &str) {
    stmts.retain(|x| x.kind.as_module_def().is_none_or(|m| m.name != name));
}

fn read_files(input: &mut clio::ClioPath) -> Result<SourceTree> {
    // Should this function move to a SourceTree constructor?
    let root = input.path();

    let mut sources = HashMap::new();
    for file in input.clone().files(has_extension("prql"))? {
        let path = file.path().strip_prefix(root)?.to_owned();

        let mut file_contents = String::new();

View on GitHub (pinned to e164e249b9)