pola-rs/polars · error · ValueError

invalid Config file (did you mean to use `load`?) {err}

Error message

invalid Config file (did you mean to use `load`?)
{err}

What it means

`pl.Config.load_from_file(file)` normalizes the path and reads it with `Path.read_text()`; any OSError (file does not exist, permission denied, path is a directory) is re-raised as ValueError prefixed 'invalid Config file (did you mean to use `load`?)'. The hint covers the inverse mistake: passing the JSON string itself to the file-based API.

Source

Thrown at py-polars/src/polars/config.py:447

    def load_from_file(cls, file: Path | str) -> Config:
        """
        Load (and set) previously saved Config options from file.

        Parameters
        ----------
        file : Path | str
            File path to a JSON string produced by `Config.save()`.

        See Also
        --------
        load : Load (and set) Config options from a JSON string.
        save : Save the current set of Config options as a JSON string or file.
        """
        try:
            options = Path(normalize_filepath(file)).read_text()
        except OSError as err:
            msg = f"invalid Config file (did you mean to use `load`?)\n{err}"
            raise ValueError(msg) from err

        return cls.load(options)

    @classmethod
    def restore_defaults(cls) -> type[Config]:
        """
        Reset all polars Config settings to their default state.

        Notes
        -----
        This method operates by removing all Config options from the environment,
        and then setting any local (non-env) options back to their default value.

        Examples
        --------
        >>> cfg = pl.Config.restore_defaults()  # doctest: +SKIP
        """
        # unset all Config environment variables

View on GitHub (pinned to 68506541d2)

Solutions

1. Verify the path: `from pathlib import Path; p = Path(file).resolve(); assert p.is_file()` and fix cwd-relative paths.
2. If you actually have a JSON string, call `pl.Config.load(cfg_string)` instead.
3. Check file permissions on the config file.

Example fix

# before
pl.Config.load_from_file("~/settings/polars.json")  # '~' not expanded, file unreadable

# after
from pathlib import Path
pl.Config.load_from_file(Path("~/settings/polars.json").expanduser())

from pathlib import Path

def load_config_file(file: str | Path) -> None:
    path = Path(file).expanduser().resolve()
    if not path.is_file():
        raise FileNotFoundError(f"config file not found: {path}")
    pl.Config.load_from_file(path)

try:
    pl.Config.load_from_file(path)
except ValueError as err:
    if "did you mean to use `load`" in str(err) and str(path).lstrip().startswith("{"):
        pl.Config.load(str(path))  # a JSON string was passed by mistake
    else:
        raise

When it happens

Trigger: `pl.Config.load_from_file('cfg.json')` where cfg.json does not exist or is unreadable; calling `load_from_file` with a JSON string instead of a path; a cwd-relative path resolved from the wrong working directory.

Common situations: Typo'd or relative config paths in scripts/notebooks; permission issues on shared or mounted config files; mixing up the argument of `load` vs `load_from_file`.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• `Config` has no option {opt!r}
• invalid Config string (did you mean to use `load_from_file`?
• `separator` must be a single character; found {separator!r}
• number of characters must be > 0
• invalid alignment: {format!r}

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-19). Data as JSON: /api/errors/0da1b4559539ce3f. Report an issue: GitHub.