asciinema/asciinema · error

appending to asciicast v1 files is not supported

Error message

appending to asciicast v1 files is not supported

What it means

Raised by get_file_format when appending (--append) to an output file detected as asciicast v1. The v1 format is a single-line JSON document that cannot be appended to; only v2 (line-based) and v3 formats support appending. asciinema refuses rather than corrupting the file.

Source

Thrown at src/cmd/session.rs:246

        }

        Ok((overwrite, append))
    }

    fn get_file_format(&self, path: &Path, append: bool) -> Result<Format> {
        self.output_format.map(Ok).unwrap_or_else(|| {
            let format_path = if is_zstd_path(path) {
                path.with_extension("")
            } else {
                path.to_owned()
            };

            if format_path.extension().is_some_and(|ext| ext == "txt") {
                Ok(Format::Txt)
            } else if append {
                match asciicast::open_from_path(path) {
                    Ok(cast) => match cast.version {
                        Version::One => bail!("appending to asciicast v1 files is not supported"),
                        Version::Two => Ok(Format::AsciicastV2),
                        Version::Three => Ok(Format::AsciicastV3),
                    },

                    Err(e) => bail!("can't append: {e}"),
                }
            } else {
                Ok(Format::AsciicastV3)
            }
        })
    }

    fn get_encoder(
        &self,
        format: Format,
        path: &Path,
        append: bool,
    ) -> Result<Box<dyn Encoder + Send>> {

View on GitHub (pinned to 7749806198)

Solutions

1. Convert the v1 file to v2/v3 first (e.g. `asciinema convert`) then append
2. Record to a new file instead of appending
3. Upgrade the recording manually to the asciicast v2/v3 line format

Example fix

// before
$ asciinema session --append old-v1.cast   // fails
// after
$ asciinema convert --overwrite old-v1.cast old-v1.cast
$ asciinema session --append old-v1.cast

// Before appending, check the cast version:
let first = std::fs::read_to_string("old.cast")?;
if first.trim().starts_with('{') && serde_json::from_str::<serde_json::Value>(&first).is_ok() {
    // v1 single-object JSON: convert to v2/v3 before appending
}

When it happens

Trigger: Running a session with --append whose output file extension is not .txt, and asciicast::open_from_path parses it as Version::One.

Common situations: Appending to very old recordings made with legacy asciinema versions; files downloaded from old archives; mistakenly appending to a v1 cast produced by an old tool.

Related errors

• can't append: {e}
• can't append: file compression doesn't match its .zst extens
• file exists, use --overwrite option to overwrite the file
• This shell is already being streamed at {url}
• This shell is already being streamed

AI-assisted analysis of asciinema/asciinema@7749806198 (2026-09-03). Data as JSON: /api/errors/2d2a1e8e91ec45e4. Report an issue: GitHub.