pola-rs/polars · error

invalid Config file (did you mean to use `load`?)\n

Error message

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

What it means

Raised by Config.load_from_file when the file path cannot be read (OSError), e.g. the file does not exist. The message hints that if you intended to parse a JSON string you should use Config.load instead.

Solutions

  1. Verify the file exists at the given path (os.path.exists)
  2. Switch to Config.load(json_string) if you already have the string
  3. Normalize/expand the path (the API applies normalize_filepath; use absolute paths)
  4. Check read permissions on the config file

Example fix

// before
pl.Config.load_from_file(json_string)  # ValueError: invalid Config file
// after
pl.Config.load(json_string)
Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
p = Path(path).expanduser()
if not p.is_file():
    raise FileNotFoundError(path)

Type guard

def config_file_ok(path: str) -> bool:
    return Path(path).expanduser().is_file()

Try / catch

try:
    pl.Config.load_from_file(path)
except ValueError as e:
    logging.error('cannot read config file: %s', e)
    raise

Prevention

When it happens

Trigger: Config.load_from_file('missing.json') with a nonexistent/unreadable path, or passing a JSON string to load_from_file instead of load.

Common situations: Wrong path or typo'd filename; confusing load/load_from_file; permission issues on the config file.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

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

Appendix: 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 fe841f959e)