pola-rs/polars · error

failed to open the schema file for writing

Error message

failed to open the schema file for writing

What it means

`generate` calls `File::create(path)` and `.expect(...)`s the result. If the file cannot be created or opened for writing (bad path, missing parent directory, permissions, path is a directory), the process panics with this message. The error's underlying io::Error is included by expect.

Solutions

1. Verify the output directory exists and create it if needed (e.g. `mkdir -p dir`).
2. Check filesystem permissions on the target path and that it is not a directory.
3. Use the default path (`./dsl-schema.json`) by omitting the path argument and run from a writable directory.

Example fix

// before
dsl-schema generate ./missing-dir/schema.json

// after
mkdir -p ./missing-dir && dsl-schema generate ./missing-dir/schema.json

import os
path = "./out/schema.json"
os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
if os.path.isdir(path):
    raise ValueError(f"{path} is a directory")
if not os.access(os.path.dirname(path) or ".", os.W_OK):
    raise PermissionError(f"cannot write to {path}")

When it happens

Trigger: `dsl-schema generate <path>` where the path's parent directory doesn't exist, the path is an existing directory, or the process lacks write permission for that location.

Common situations: Typo'd output path, read-only filesystem/CI container, running without permissions in the target directory, or forgetting to create the output directory first.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• failed to flush the schema file
• failed to write the last newline
• failed to write the schema into the file
• could not read
• Expecting to be able to downcast into bytes from read…

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/b6ba811cea68faff. Report an issue: GitHub.

Appendix: source

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

            "update-hashes" => {
                update_hashes(path.unwrap_or(DEFAULT_HASHES_PATH.to_owned()));
            },
            "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");

View on GitHub (pinned to fe841f959e)