Currently `annotate` only works with a single source, but…

Error message

Currently `annotate` only works with a single source, but found multiple sources: {:?}

What it means

The hidden `prqlc debug annotate` command annotates a single PRQL source, so like `lex` it requires exactly one input. If multiple sources are present, it bails listing all source names back-quoted, to show which files conflicted.

Solutions

Invoke annotate with a single standalone .prql file
Temporarily inline included modules into one file before annotating
Read the listed source names in the message and remove all but the intended one from the input set

Example fix

# before
prqlc debug annotate project/ --include project/helpers.prql
# after
prqlc debug annotate project/main.prql

Defensive patterns

Strategy: validation

Validate before calling

# Single-file check for debug annotate
[ -f "$1" ] && [ "$(find "$1" -name '*.prql' | wc -l)" -le 1 ] && prqlc debug annotate "$1"

Try / catch

prqlc debug annotate main.prql 2>&1 | grep -v 'single source' || true

Prevention

Annotate one standalone file at a time
Inline includes into one file when whole-project annotation is needed
Read the listed source names in the error to identify extra inputs

When it happens

Trigger: Running `prqlc debug annotate` with a project or file set that resolves to more than one source (multiple files, main + includes).

Common situations: Exploring compiler annotations on a multi-file project; accidentally passing a directory instead of a single file.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

                    // TODO: allow multiple sources
                    bail!("Currently `lex` only works with a single source, but found multiple sources")
                })?;
                let tokens = prql_to_tokens(s)?;
                match format {
                    Format::Json => serde_json::to_string_pretty(&tokens)?.into_bytes(),
                    Format::Yaml => serde_yaml::to_string(&tokens)?.into_bytes(),
                }
            }
            Command::Collect(_) => {
                let mut root_module_def = prql_to_pl_tree(sources)?;

                drop_module_def(&mut root_module_def.stmts, "std");

                pl_to_prql(&root_module_def)?.into_bytes()
            }
            Command::Debug(DebugCommand::Annotate(_)) => {
                let (_, source) = sources.sources.clone().into_iter().exactly_one().or_else(
                    |_| bail!(
                        "Currently `annotate` only works with a single source, but found multiple sources: {:?}",
                        sources.sources.keys()
                            .map(|x| x.display().to_string())
                            .sorted()
                            .map(|x| format!("`{x}`"))
                            .join(", ")
                    )
                )?;

                // TODO: potentially if there is code performing a role beyond
                // presentation, it should be a library function; and we could
                // promote it to the `prqlc` crate.
                let root_mod = prql_to_pl(&source)?;

                // resolve
                let ctx = semantic::resolve(root_mod)?;

                let frames = if let Ok((main, _)) = ctx.find_main_rel(&[]) {

View on GitHub (pinned to e164e249b9)