The option "--file-stem" cannot be used when exporting…

Error message

The option "--file-stem" cannot be used when exporting multiple rnote files.

What it means

For the `docpages` export subcommand, --file-stem supplies the base name for each generated page file. When exporting multiple rnote files at once, a single stem would make pages from different documents collide or be ambiguous, so the CLI rejects combining --file-stem with more than one input file.

Solutions

Drop --file-stem when exporting multiple files and let each document derive its own stem.
Export one file at a time (one invocation per rnote file) if you need a custom --file-stem.
Update scripts to conditionally add --file-stem only when a single input file is given.

Example fix

// before
rnote export docpages a.rnote b.rnote --file-stem page
// after
rnote export docpages a.rnote b.rnote
// or per-file:
rnote export docpages a.rnote --file-stem page

Defensive patterns

Strategy: validation

Validate before calling

if [ "$#" -gt 1 ] && [[ "$ARGS" == *"--file-stem"* ]]; then echo "--file-stem only valid with a single input"; exit 2; fi

Prevention

Use --file-stem only for single-file docpages exports.
Build CLI arguments conditionally based on the input file count.
Prefer default stems for batch exports.

When it happens

Trigger: Running `rnote export docpages file1.rnote file2.rnote --file-stem page` — i.e. DocPages with rnote_files.len() > 1 and Some(output_file_stem).

Common situations: Batch-exporting several documents while reusing a single-file command line out of habit; scripts that append --file-stem unconditionally regardless of input count.

Related errors

AI-assisted analysis of flxzt/rnote@bbc5354502 (2026-09-08). Data as JSON: /api/errors/3ae9292c0be68699. Report an issue: GitHub.

Appendix: source

Thrown at crates/rnote-cli/src/export.rs:44

) -> anyhow::Result<()> {
    if rnote_files.is_empty() {
        return Err(anyhow::anyhow!(
            "There must be at least one rnote file specified for exporting."
        ));
    }

    let config = EngineConfigShared::default();
    let mut engine = Engine::default();
    let _ = engine.install_config(&config, None);
    let mut on_conflict_overwrite = None;
    let output_file = match &export_command {
        cli::ExportCommand::Doc { file_args, .. } => file_args.output_file.as_ref(),
        cli::ExportCommand::Selection { file_args, .. } => file_args.output_file.as_ref(),
        cli::ExportCommand::DocPages {
            output_file_stem, ..
        } => {
            if rnote_files.len() > 1 && output_file_stem.is_some() {
                return Err(anyhow::anyhow!(
                    "The option \"--file-stem\" cannot be used when exporting multiple rnote files."
                ));
            }
            None
        }
    };

    apply_export_prefs(
        &config,
        &export_command,
        output_file,
        no_background,
        no_pattern,
        optimize_printing,
    )?;

    match output_file {
        Some(output_file) => {

View on GitHub (pinned to bbc5354502)