pola-rs/polars · error · ValueError

invalid Config string (did you mean to use `load_from_file`?

Error message

invalid Config string (did you mean to use `load_from_file`?)

What it means

`pl.Config.load(cfg)` expects a JSON *string* produced by `Config.save()` and immediately runs `json.loads` on it. If the input is not valid JSON — most commonly because a file path was passed instead of the file's contents — polars raises ValueError with a hint pointing you to `load_from_file`, the path-based variant.

Source

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

    def load(cls, cfg: str) -> Config:
        """
        Load (and set) previously saved Config options from a JSON string.

        Parameters
        ----------
        cfg : str
            JSON string produced by `Config.save()`.

        See Also
        --------
        load_from_file : Load (and set) Config options from a JSON file.
        save : Save the current set of Config options as a JSON string or file.
        """
        try:
            options = json.loads(cfg)
        except json.JSONDecodeError as err:
            msg = "invalid Config string (did you mean to use `load_from_file`?)"
            raise ValueError(msg) from err

        cfg_load = Config()
        opts = options.get("environment", {})
        if "POLARS_ENGINE_AFFINITY" in opts:
            # A saved affinity value replaces any object affinity.
            set_engine_affinity_override(None)
        for key, opt in opts.items():
            if opt is None:
                os.environ.pop(key, None)
            else:
                os.environ[key] = opt

        for cfg_methodname, value in options.get("direct", {}).items():
            if hasattr(cfg_load, cfg_methodname):
                getattr(cfg_load, cfg_methodname)(value)

        plr.config_reload_env_vars()
        return cfg_load

View on GitHub (pinned to 68506541d2)

Solutions

For a file path, use `pl.Config.load_from_file('polars_config.json')`.
For a string, pass the exact output of `pl.Config.save()` or `Path('polars_config.json').read_text()`.
Validate hand-edited strings with `json.loads` first and fix any syntax errors it reports.

Example fix

# before
pl.Config.load("polars_config.json")  # it's a path -> invalid Config string

# after
pl.Config.load_from_file("polars_config.json")

Defensive patterns

Strategy: validation

Validate before calling

import json

def load_config(cfg: str) -> None:
    if not cfg.lstrip().startswith("{"):
        raise ValueError("cfg does not look like JSON — for a file path use pl.Config.load_from_file(cfg)")
    json.loads(cfg)  # fail fast with a precise JSON error
    pl.Config.load(cfg)

Try / catch

try:
    pl.Config.load(cfg)
except ValueError as err:
    if "did you mean to use `load_from_file`" in str(err):
        pl.Config.load_from_file(cfg)  # it was a path after all
    else:
        raise

Prevention

Convention: strings from Config.save() go to load(), filesystem paths go to load_from_file().
Validate config strings with json.loads before loading them in tests.
Store saved config in one place and load it through a single helper to avoid mixing APIs.

When it happens

Trigger: `pl.Config.load('polars_config.json')` (a path, not JSON); a truncated or hand-edited save string with syntax errors; passing an empty string.

Common situations: Confusing `load` (string) with `load_from_file` (path); hand-editing a saved config and breaking the JSON; storing the save string in a database and retrieving it truncated.

Related errors

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