VectifyAI/PageIndex · error · ValueError

Unknown config keys: {unknown_keys}

Error message

Unknown config keys: {unknown_keys}

What it means

The config loader validates user-supplied keys against the known defaults plus _MODEL_KEYS and rejects anything unknown, to catch typos before they silently do nothing.

Source

Thrown at pageindex/utils.py:1082

                  chat_model=chat, retrieve_model=chat)


class ConfigLoader:
    def __init__(self, default_path: str = None):
        if default_path is None:
            default_path = Path(__file__).parent / "config.yaml"
        self._default_dict = self._load_yaml(default_path)

    @staticmethod
    def _load_yaml(path):
        with open(path, "r", encoding="utf-8") as f:
            return yaml.safe_load(f) or {}

    def _validate_keys(self, user_dict):
        unknown_keys = (set(user_dict) - set(self._default_dict)
                        - set(_MODEL_KEYS))
        if unknown_keys:
            raise ValueError(f"Unknown config keys: {unknown_keys}")

    def load(self, user_opt=None) -> config:
        """
        Load the configuration, merging user options with default values.
        """
        if user_opt is None:
            user_dict = {}
        elif isinstance(user_opt, config):
            user_dict = vars(user_opt)
        elif isinstance(user_opt, dict):
            user_dict = user_opt
        else:
            raise TypeError("user_opt must be dict, config(SimpleNamespace) or None")

        self._validate_keys(user_dict)
        merged = {**self._default_dict, **user_dict}
        _resolve_models(merged)
        return config(**merged)

View on GitHub (pinned to afb5e11976)

Solutions

1. Read the error: it prints the exact unknown key set — fix or remove those keys
2. Compare against the default config dict / current docs for valid key names
3. Pin or migrate config files when upgrading library versions

Example fix

# before
load({'summary_model': 'gpt-4o', 'summary_modeel': 'gpt-4o'})
# after
load({'summary_model': 'gpt-4o'})

KNOWN = set(default_config_dict) | set(_MODEL_KEYS)
unknown = set(user_cfg) - KNOWN
if unknown:
    raise ValueError(f'fix config first: {unknown}')
result = load(user_cfg)

def has_only_known_keys(cfg: dict, known: set) -> bool:
    return isinstance(cfg, dict) and set(cfg) <= known

try:
    cfg = load(user_cfg)
except ValueError as e:
    if 'Unknown config keys' in str(e):
        bad = ast.literal_eval(str(e).split(': ', 1)[1])
        cfg = load({k: v for k, v in user_cfg.items() if k not in bad})
    else:
        raise

When it happens

Trigger: Calling config load (e.g. ConfigDict.load(user_opt)) with a dict containing a misspelled or outdated key, such as 'summary_model_typo', 'optimise', or a key removed in a newer version.

Common situations: Upgrading the library and using old config keys, copy-pasting example config from incompatible docs, or misspelled YAML options.

Related errors

• Unknown chat keys ({keys}) — chat takes "model" and "backend
• Unsupported PDF parser: {pdf_parser}
• chat is an empty string — pass a model name, or "cloud" for
• chat is an empty dict — chat takes "model" and "backend" (yo
• chat declares mode "cloud" but carries ({keys}) — the manage

AI-assisted analysis of VectifyAI/PageIndex@afb5e11976 (2026-08-27). Data as JSON: /api/errors/5b2d751fd1d94ced. Report an issue: GitHub.