pola-rs/polars · error

failed to flush the schema file

Error message

failed to flush the schema file

What it means

Panics in generate() when File::flush fails after serializing the DSL schema to disk, typically because the underlying write errored (disk full, permissions, or the file was closed). It guards the final durability step of writing the schema JSON file.

Source

Thrown at crates/polars-plan/src/bin/dsl-schema.rs:80

            "check-hashes" => {
                check_hashes(path.unwrap_or(DEFAULT_HASHES_PATH.to_owned()));
            },
            unknown => {
                panic!("unknown command: `{unknown}`");
            },
        }
    }

    /// Serializes the current DSL schema into a file at the given path.
    ///
    /// Any existing file at the path is overwritten.
    fn generate(path: impl AsRef<Path>) {
        let schema = DslPlan::dsl_schema();

        let mut file = File::create(path).expect("failed to open the schema file for writing");
        serde_json::to_writer_pretty(&mut file, &schema).expect("failed to serialize the schema");
        writeln!(&mut file).expect("failed to write the last newline");
        file.flush().expect("failed to flush the schema file");
    }

    /// Outputs the current DSL schema hashes into a file at the given path.
    ///
    /// Any existing file at the path is overwritten.
    fn update_hashes(path: impl AsRef<Path>) {
        std::fs::write(path, current_schema_hashes())
            .expect("failed to write the schema into the file");
        eprintln!("the DSL schema file was updated");
    }

    /// Checks that the current schema hashes match the schema hashes in the file.
    fn check_hashes(path: impl AsRef<Path>) {
        let file_hashes =
            std::fs::read_to_string(path).expect("failed to read the schema hashes from the file");
        let expected = current_schema_hashes();
        if file_hashes != expected {
            eprintln!("the schema hashes are not up to date, run `make update-dsl-schema-hashes`");

View on GitHub (pinned to 9b5d73fd00)

Solutions

1. Check write permissions and disk space for the schema file; flushing it to disk failed.
2. Ensure no other process holds the file open.

When it happens

Trigger: This panic/expect fires when execution reaches an unguarded state described by: "failed to flush the schema file". Typical triggers: unsupported dtype or feature-gated code path reached at runtime, invalid user input or environment variable value, calling API methods in the wrong order or on mismatched types, or data (lengths, offsets, ranges) violating the function's preconditions.

Common situations: Encountered when input data or configuration does not meet the preconditions of the throwing code path ("failed to flush the schema file"). Common cases: missing Cargo feature flags, mismatched dtypes/lengths between arrays or series, out-of-range temporal values, malformed environment variables, or operations on unsupported/complex nested types.

AI-assisted analysis of pola-rs/polars@9b5d73fd00 (2026-08-19). Data as JSON: /api/errors/403a74483cfdc77a. Report an issue: GitHub.