What causes "could not prepare output" in Y2Z/monolith?

Create the parent directory of the output path first (mkdir -p) or correct the -o path typo.

could not prepare output

Error message

could not prepare output

What it means

This panic comes from the `expect("could not prepare output")` on `Output::new()` in main.rs:283 (the STDIN-pipe branch, target == "-"). `Output::new` returns `Err(io::Error)` only when a destination file path was given and `fs::File::create(final_destination)` fails — i.e. the output cannot be opened for writing. It is a hard panic, not a graceful error, because it happens inside the Ok-branch of document creation after all network work succeeded.

Source

Thrown at src/main.rs:283

    // Initiate session
    let output_format = options.output_format.clone();
    let silent = options.silent;
    let session: Session = Session::new(cache, cookies, options);

    // Retrieve target from source and output result
    if cli.target == "-" {
        // Read input from pipe (STDIN)
        let data: Vec<u8> = read_stdin();

        match create_monolithic_document_from_data(session, data, None, None) {
            Ok((result, title)) => {
                // Define output
                let mut output = Output::new(
                    &destination.unwrap_or(String::new()),
                    &title.unwrap_or_default(),
                    output_format,
                )
                .expect("could not prepare output");

                // Write result into STDOUT or file
                output.write(&result).expect("could not write output");
            }
            Err(error) => {
                if !silent {
                    print_error_message(&format!("Error: {}", error));
                }

                exit_code = 1;
            }
        }
    } else {
        match create_monolithic_document(session, cli.target) {
            Ok((result, title)) => {
                // Define output
                let mut output = Output::new(
                    &destination.unwrap_or(String::new()),

View on GitHub (pinned to a6fc8d0095)

Solutions

Create the parent directory of the output path first (mkdir -p) or correct the -o path typo.
Verify write permissions for the user running monolith on the destination directory.
Quote/escape the -o argument and avoid letting the document title inject illegal characters into the filename; pass an explicit simple filename.
Check available disk space and that the destination is not itself a directory.
If scripting, guard with a pre-flight writability check (e.g. `touch <dir>/.write_test`) before invoking monolith.

Example fix

// before (shell)
cat page.html | monolith - -o out/page.html   # out/ does not exist -> panic

// after (shell)
mkdir -p out && cat page.html | monolith - -o out/page.html

Defensive patterns

Strategy: validation

Validate before calling

#!/usr/bin/env bash
out="out/page.html"
dir="$(dirname "$out")"
mkdir -p "$dir" || exit 1
[ -d "$out" ] && { echo "output path is a directory"; exit 1; }
[ -w "$dir" ] || { echo "no write permission in $dir"; exit 1; }
printf '' > "$out.tmp" && rm "$out.tmp" || { echo "cannot create $out"; exit 1; }
cat page.html | monolith - -o "$out"

Prevention

Always create the destination directory (mkdir -p) before running with -o.
Pass an explicit, simple filename; avoid templates that interpolate the page title into the path.
Check directory writability in CI/scripts before invoking monolith.
Remember this is a panic (exit code 101), not a graceful error — treat non-zero exits accordingly.

When it happens

Trigger: Running monolith with `-` (or with piped input via `target == "-"`) AND a non-empty `-o/--output` destination whose file cannot be created: nonexistent parent directory, permission denied, path is a directory, invalid characters in the path (possibly produced by `format_output_path` substituting the page title into the filename), disk full, or read-only filesystem.

Common situations: Users pipe a page in via stdin (`curl ... | monolith - -o out.html`) while the output directory doesn't exist or is read-only; titles containing `/` or other filesystem-illegal characters interpolated into the output path; running as a user without write permission in the current directory; on Windows, reserved characters (`:`, `?`, `*`) coming from a document title.

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

AI-assisted analysis of Y2Z/monolith@a6fc8d0095 (2026-09-05). Data as JSON: /api/errors/991c5eefdd662401. Report an issue: GitHub.