{"record":{"id":"a0449cd7f08b0ccc","repo":"pola-rs/polars","slug":"path","errorCode":null,"errorMessage":"{}: {path}","messagePattern":"\\{\\}: \\{path\\}","errorType":"exception","errorClass":"PolarsError::IO","httpStatus":null,"severity":"error","filePath":"crates/polars-utils/src/io.rs","lineNumber":52,"sourceCode":"                self.source\n            )\n        } else {\n            write!(f, \"{}: {path}\", self.source)\n        }\n    }\n}\n\nimpl std::error::Error for PathIoError {\n    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {\n        Some(&self.source)\n    }\n}\n\n/// Attaches `path` to `err`, keeping its [`io::ErrorKind`].\n///\n/// The path is available in full through [`PathIoError`], and truncated in the message.\npub fn _limit_path_len_io_err(path: &Path, err: io::Error) -> PolarsError {\n    io::Error::new(\n        err.kind(),\n        PathIoError {\n            path: path.to_path_buf(),\n            source: err,\n        },\n    )\n    .into()\n}\n\npub fn open_file(path: &Path) -> PolarsResult<File> {\n    File::open(path).map_err(|err| _limit_path_len_io_err(path, err))\n}\n\npub fn open_file_write(path: &Path) -> PolarsResult<File> {\n    std::fs::OpenOptions::new()\n        .write(true)\n        .create(true)\n        .truncate(true)","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/crates/polars-utils/src/io.rs#L34-L70","documentation":"This error wraps an I/O error (e.g. file-not-found, permission denied) with the full path involved, preserving the original io::ErrorKind. Polars attaches the path so the message stays readable (long paths are truncated in the message, full path available via PathIoError). It is a context-adding wrapper, not a failure class of its own — the underlying kind (NotFound, PermissionDenied, etc.) determines what went wrong.","triggerScenarios":"Any Polars operation that resolves a file path and fails at the OS level: reading/scanning a file (expand_path_cloud, open_blocking, open_file), memory-mapping a file (try_new_mmap_from_path), or creating directories recursively (mkdir_recursive, tokio_mkdir_recursive) when the path does not exist, is misspelled, or lacks permissions.","commonSituations":"Typos in file paths, reading files that were moved or deleted between existence check and open, relative paths resolved from an unexpected working directory, cloud-storage paths passed without the right prefix/credentials, insufficient permissions on the target path or parent directory when creating directories.","solutions":["Verify the path exists and is spelled correctly: run `ls <path>` (or the equivalent for your storage backend) before calling the Polars API.","Use absolute paths to avoid working-directory surprises, and confirm the path prefix matches the IO plugin/cloud scheme you intend (s3://, gs://, file://).","Check permissions on the file or parent directory, and on any directories mkdir_recursive will create.","Inspect the wrapped PathIoError / err.kind() in the message to distinguish NotFound vs PermissionDenied vs other OS errors and fix accordingly."],"exampleFix":"// before\nlf = pl.scan_csv(\"mydat.csv\")  # FileNotFoundError: path attached\n// after\nfrom pathlib import Path\np = Path(\"data/mydat.csv\")\nassert p.exists(), f\"missing input: {p}\"\nlf = pl.scan_csv(str(p))","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\ndef ensure_readable(p):\n    path = Path(p)\n    if not path.exists():\n        raise FileNotFoundError(p)\n    if not path.is_file():\n        raise IsADirectoryError(p)\n    if not os.access(path, os.R_OK):\n        raise PermissionError(p)\n    return str(path.resolve())","typeGuard":null,"tryCatchPattern":"try:\n    lf = pl.scan_csv(path)\nexcept (FileNotFoundError, PermissionError, OSError) as e:\n    kind = getattr(getattr(e, '__cause__', e), 'errno', None)\n    log.error(f\"IO failed for path: {e}\")\n    raise","preventionTips":["Check path existence and permissions before the call","Use absolute, normalized paths","Never assume a file checked earlier still exists (TOCTOU) — handle the error","Log the full wrapped PathIoError to distinguish NotFound vs PermissionDenied"],"tags":["io","filesystem","rust","path-handling"],"backgroundTag":"file-not-found","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-09-10T10:08:55.499Z","contentChangedAt":"2026-09-10T10:08:55.499Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}