How Hypster Handles Unknown or Unreachable Parameters During Configuration

Hypster reconciles user-supplied values with actual parameter access through a three-stage process that tracks called parameters, detects mismatches, and applies a configurable on_unknown policy to handle typos or unreachable conditional branches.

When building configuration spaces with the gilad-rubin/hypster library, users often supply values for parameters that might not exist or reside on conditional branches that never execute. The library's instantiate function implements a robust validation mechanism to identify and handle these unknown or unreachable parameters gracefully.

The Three-Stage Parameter Reconciliation Process

The reconciliation logic resides primarily in src/hypster/core.py and operates through three distinct phases that ensure only valid, accessed parameters are accepted while providing clear feedback for mismatches.

Stage 1: Tracking Called Parameters via HP.called_params

Every call to an hp method (such as hp.bool(), hp.int(), or hp.select()) records the full dotted name of the parameter in HP.called_params. This tracking occurs within the HP._handle_* methods defined in src/hypster/hp.py.

After the user-provided configuration function returns, instantiate computes the delta between the original state and the final called parameters:

# src/hypster/core.py L62-L64

called_params = hp.called_params - original_called_params
_handle_unknown_parameters(values, called_params, on_unknown)

Stage 2: Detecting Unknown and Unreachable Values

The _handle_unknown_parameters function in src/hypster/core.py receives the user-supplied values dictionary, the set of called_params, and the on_unknown policy. It identifies discrepancies by filtering out parameters that were never touched during execution:

# src/hypster/core.py L78-L80

unknown_params = set(provided_values.keys()) - called_params

Unreachable parameters are those that exist in the configuration space but reside on conditional branches that the function never entered. Because they were never called, they appear in unknown_params exactly like misspelled or nonexistent names. This unified treatment simplifies error handling while ensuring no orphaned values pass silently.

Stage 3: Applying the on_unknown Policy

The on_unknown parameter accepts one of three string literals: "warn" (default), "raise", or "ignore". The policy execution logic in src/hypster/core.py handles each case:

• ignore – Returns silently, discarding stray values (lines 75-76)
• warn – Emits a UserWarning with details about the unknown parameters (lines 105-106)
• raise – Raises a ValueError immediately (lines 103-104)

Before emitting warnings or errors, Hypster attempts to suggest corrections for potential typos using the suggest_similar_names helper from src/hypster/utils.py:

# src/hypster/core.py L86-L89

similar = suggest_similar_names(unknown, list(called_params), threshold=0.6)

If similar names are found above the 0.6 similarity threshold, the error message includes the most likely candidate with a percentage match (lines 96-98). Otherwise, the message simply reports "Unknown parameter."

Configuring Error Handling with on_unknown

The on_unknown parameter provides flexibility for different development scenarios, from strict validation in production to permissive experimentation in research.

Example 1: Default Warning Behavior

By default, instantiate warns about unknown parameters without failing:

from hypster import instantiate, hp

def my_cfg(hp: hp.HP):
    if hp.bool(name="use_tree", default=False):
        hp.int(name="n_trees", default=100)

instantiate(
    my_cfg,
    values={"use_tree": True, "n_trees": 200, "typo_param": 42},
    on_unknown="warn",  # default, can be omitted

)

# Emits: UserWarning: Unknown or unreachable parameters: 'typo_param': Unknown parameter

Example 2: Strict Validation with Raise

For production pipelines where configuration errors must halt execution immediately:

try:
    instantiate(
        my_cfg,
        values={"use_tree": False, "n_trees": 200},  # n_trees is unreachable

        on_unknown="raise",
    )
except ValueError as e:
    print(e)

# ValueError: Unknown or unreachable parameters: 'n_trees': Unknown parameter

Example 3: Silent Ignore Mode

When integrating with external configuration systems that may pass extra values:

cfg = instantiate(
    my_cfg,
    values={"use_tree": True, "unused_key": "ignored"},
    on_unknown="ignore",
)

# No output, no error; configuration proceeds with valid parameters only

Typo Detection and Friendly Error Messages

Hypster enhances the developer experience by suggesting corrections when unknown parameters resemble valid ones. The fuzzy-matching logic in src/hypster/utils.py calculates string similarity using a threshold of 0.6:

# src/hypster/utils.py L8

def suggest_similar_names(target, candidates, threshold=0.6):
    # Returns list of (candidate, similarity_score) tuples above threshold

    ...

When on_unknown="warn" or "raise" is active and similar names are detected, the error message includes suggestions:

Unknown or unreachable parameters:
  - 'n_estimators': Did you mean 'n_trees' (85% similar)?

This feature significantly reduces debugging time when refactoring configuration names or working with large parameter spaces.

Summary

• Parameter tracking: Hypster records every parameter access in HP.called_params during configuration execution, creating an authoritative set of "called" parameters.
• Unified detection: Both truly unknown names and unreachable conditional parameters are identified by comparing user-supplied values against the called set in _handle_unknown_parameters.
• Configurable policies: The on_unknown argument supports "warn" (default), "raise", and "ignore" modes to accommodate strict validation or permissive integration scenarios.
• Intelligent suggestions: When errors occur, Hypster uses suggest_similar_names from src/hypster/utils.py to propose corrections based on 60% string similarity threshold.

Frequently Asked Questions

What happens if I misspell a parameter name in my values dictionary?

Hypster treats misspelled names as unknown parameters. If on_unknown="warn" (the default), you will receive a UserWarning listing the unknown parameter. If the misspelling closely resembles a valid parameter name (above 0.6 similarity), Hypster suggests the correct name in the warning message. With on_unknown="raise", a ValueError is raised instead.

How does Hypster distinguish between unknown parameters and conditional parameters that weren't reached?

It does not distinguish them during detection. Both scenarios result in parameters that never get recorded in HP.called_params. When _handle_unknown_parameters compares your provided values against the called set, any parameter not in the called set—whether misspelled or on an unexecuted conditional branch—is flagged as unknown/unreachable. This unified handling simplifies the API while ensuring no stray values pass silently.

Can I disable warnings for extra parameters when loading external configuration files?

Yes. Pass on_unknown="ignore" to the instantiate function. This mode silently discards any values that do not correspond to called parameters, making it ideal for integrating with external configuration systems (like YAML or JSON files) that may contain extra keys not relevant to the current configuration function.

What is the similarity threshold for typo suggestions, and can I adjust it?

The default threshold is 0.6 (60% similarity), hardcoded in the call to suggest_similar_names within _handle_unknown_parameters in src/hypster/core.py. Currently, this threshold is not exposed as a configurable parameter in the public API; users must modify the source code in src/hypster/utils.py if they need different sensitivity for fuzzy matching.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}