# How Hypster Handles Unknown or Unreachable Parameters During Configuration

> Learn how Hypster manages unknown or unreachable parameters during configuration. Discover its three-stage process for detecting mismatches and applying on_unknown policies for robust error handling.

- Repository: [Gilad Rubin/hypster](https://github.com/gilad-rubin/hypster)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp.py).

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

```python

# 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`](https://github.com/gilad-rubin/hypster/blob/main/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:

```python

# 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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/utils.py):

```python

# 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:

```python
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:

```python
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:

```python
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`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/utils.py) calculates string similarity using a threshold of 0.6:

```python

# 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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/utils.py) if they need different sensitivity for fuzzy matching.