# How to Handle Configuration Errors Gracefully with Custom Messages in Hypster

> Handle configuration errors gracefully in Hypster using custom messages and the on unknown parameter. Learn to warn raise or ignore unknown parameters for better error handling.

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

---

**Hypster validates configuration functions at instantiation time and provides a unified error-handling flow through the `on_unknown` parameter, allowing you to warn, raise, or ignore unknown parameters with helpful typo suggestions.**

Handling configuration errors gracefully is critical for maintaining robust machine learning pipelines. The `gilad-rubin/hypster` library provides a structured approach to configuration validation that catches errors early and delivers clear, actionable feedback. This guide explores how to leverage Hypster's error handling mechanisms to manage unknown parameters and customize error messages effectively.

## Understanding Hypster's Error Handling Architecture

Hypster implements a three-stage validation pipeline that ensures configuration integrity before execution completes. Each stage targets specific failure modes and provides detailed diagnostics.

### Signature Validation

Before executing any configuration function, Hypster verifies that the function signature accepts an `HP` instance as its first parameter. This check occurs in `utils.validate_config_func_signature` (lines 85-118 in [`src/hypster/utils.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/utils.py)). If the signature is invalid, Hypster raises a `ValueError` immediately, preventing cryptic runtime errors later in the pipeline.

### Execution and Parameter Tracking

During instantiation, the `instantiate` function (lines 17-71 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py)) creates an `HP` instance that tracks every hyperparameter accessed via the `original_called_params` and `called_params` attributes. This tracking enables Hypster to distinguish between parameters that were actually consumed by the configuration function versus those that were supplied but never accessed.

### Unknown Parameter Handling

The `_handle_unknown_parameters` function (lines 73-107 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py)) serves as the central dispatcher for error handling. This function compares the set of supplied parameter keys against the set of accessed parameters, then applies the user-specified `on_unknown` policy to determine the appropriate response.

## Controlling Error Behavior with the `on_unknown` Parameter

Hypster provides granular control over how the system reacts to unknown or unreachable parameters through the `on_unknown` flag. This parameter accepts three distinct string values that dictate the severity of the response.

### Warning Policy (Default)

When `on_unknown="warn"` (the default), Hypster emits a `UserWarning` containing a diagnostic message that lists the problematic parameters. This non-fatal approach allows execution to continue while alerting developers to potential configuration issues.

### Raise Policy

Setting `on_unknown="raise"` triggers a `ValueError` with the same descriptive message. This strict mode is recommended for production environments where silent parameter mismatches could lead to incorrect model configurations.

### Ignore Policy

The `on_unknown="ignore"` setting silently discards unknown parameters without warnings or exceptions. This mode is useful when configuration dictionaries contain metadata or auxiliary values that should not trigger validation logic.

### Typo Suggestion Engine

When unknown parameters are detected, Hypster's `suggest_similar_names` utility (utilized within `_handle_unknown_parameters` at lines 85-90 and 92-99 in [`core.py`](https://github.com/gilad-rubin/hypster/blob/main/core.py)) employs Levenshtein-style string similarity to identify potential typos. If the similarity score exceeds a threshold, the error message includes suggestions such as:

```

Unknown or unreachable parameters:
  - 'lerning_rate': Did you mean 'learning_rate'? (similarity: 78%)

```

## Practical Code Examples

### Basic Usage with Default Warnings

The following example demonstrates the default warning behavior when supplying an unused parameter:

```python
from hypster import HP, instantiate

def cfg(hp: HP):
    lr = hp.float(0.1, name="learning_rate")
    return {"lr": lr}

# Supplies an extra key that is never used → warning is emitted

import warnings
warnings.simplefilter("always")
with warnings.catch_warnings(record=True) as ws:
    result = instantiate(cfg, values={"unknown_param": 0.05})
    assert result == {"lr": 0.1}
    assert len(ws) == 1
    assert "'unknown_param': Unknown parameter" in str(ws[0].message)

```

*Relevant code*: The warning is produced by `_handle_unknown_parameters` when `on_unknown="warn"` (see lines 73-107 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py)).

### Raising Exceptions for Unknown Parameters

For strict validation, configure Hypster to raise `ValueError` when encountering unknown parameters:

```python
from hypster import HP, instantiate
import pytest

def cfg(hp: HP):
    lr = hp.float(0.1, name="learning_rate")
    return {"lr": lr}

with pytest.raises(ValueError, match="Unknown or unreachable"):
    instantiate(cfg, values={"unknown_param": 0.05}, on_unknown="raise")

```

*Relevant code*: The `raise ValueError(error_message)` branch on line 104 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py).

### Getting Typo Suggestions

Hypster automatically suggests corrections for parameter names that closely match known values:

```python
from hypster import HP, instantiate
import warnings

def cfg(hp: HP):
    learning_rate = hp.float(0.1, name="learning_rate")
    temperature = hp.float(0.7, name="temperature")
    return {"lr": learning_rate, "temp": temperature}

warnings.simplefilter("always")
with warnings.catch_warnings(record=True) as ws:
    instantiate(cfg, values={"lerning_rate": 0.05})
    print(ws[0].message)   # → contains "...'lerning_rate': Did you mean 'learning_rate'?"

```

*Relevant code*: Suggestion creation at lines 85-90 and message formatting at 92-99 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py).

### Silencing Unknown Parameters

To suppress all warnings and errors for unknown parameters:

```python
from hypster import HP, instantiate

def cfg(hp: HP):
    lr = hp.float(0.1, name="learning_rate")
    return {"lr": lr}

result = instantiate(cfg, values={"unused": 123}, on_unknown="ignore")
assert result == {"lr": 0.1}

```

*Relevant code*: Early return on line 75 of `_handle_unknown_parameters` in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py).

### Custom Error Handling

For advanced use cases, you can replace the default error handler with custom logic:

```python
import logging
from hypster.core import _handle_unknown_parameters

# Replace the default handler with a logger‑based one

def logged_handler(values, called, policy):
    if policy == "warn":
        logging.warning("Hypster unknown params: %s", values)
    else:
        # fall back to original behaviour for raise/ignore

        _handle_unknown_parameters(values, called, policy)

# Monkey‑patch for the current process (only for demonstration)

import hypster.core as core
core._handle_unknown_parameters = logged_handler

```

*Why this works*: The entire message‑generation logic lives in a single function, making it safe to replace or wrap.

## Key Source Files and Functions

| File | Purpose | Link |
|------|---------|------|
| [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py) | Core `instantiate` API, unknown‑parameter handling, error‑policy orchestration | [core.py](https://github.com/gilad-rubin/hypster/blob/master/src/hypster/core.py) |
| [`src/hypster/utils.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/utils.py) | Validation of config‑function signatures and helper utilities (e.g., `suggest_similar_names`) | [utils.py](https://github.com/gilad-rubin/hypster/blob/master/src/hypster/utils.py) |
| [`src/hypster/hp.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp.py) | Definition of the `HP` class that tracks called parameters | [hp.py](https://github.com/gilad-rubin/hypster/blob/master/src/hypster/hp.py) |
| [`tests/test_error_handling.py`](https://github.com/gilad-rubin/hypster/blob/main/tests/test_error_handling.py) | Test suite demonstrating the three policies and typo suggestions | [test_error_handling.py](https://github.com/gilad-rubin/hypster/blob/master/tests/test_error_handling.py) |

## Summary

- **Hypster validates configurations at instantiation time** through a three-stage pipeline: signature validation, parameter tracking, and unknown parameter handling.
- **The `on_unknown` parameter controls error severity** with three modes: `"warn"` (default), `"raise"`, and `"ignore"`.
- **Typo detection uses Levenshtein-style similarity** to suggest corrections when unknown parameter names closely match valid ones.
- **All validation errors raise `ValueError`** consistently, making exception handling straightforward in production code.
- **The `_handle_unknown_parameters` function is extensible**, allowing you to monkey-patch or subclass the error handling logic for custom logging or messaging.

## Frequently Asked Questions

### What error type does Hypster raise for configuration errors?

Hypster consistently raises **`ValueError`** for all configuration validation failures. This includes signature mismatches detected in `utils.validate_config_func_signature` and unknown parameter violations handled by `_handle_unknown_parameters`. Using a single exception type simplifies error handling in your application, allowing you to catch configuration issues with a single `except ValueError` block.

### How does Hypster suggest corrections for typos in parameter names?

When you supply a parameter name that is not accessed by the configuration function, Hypster's `suggest_similar_names` utility (located in [`src/hypster/utils.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/utils.py)) calculates Levenshtein-style similarity scores between the unknown name and all valid parameters. If the similarity exceeds a threshold, the error or warning message includes a suggestion such as "Did you mean 'learning_rate'?" This functionality is integrated into `_handle_unknown_parameters` at lines 85-99 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py).

### Can I customize the error messages without modifying the source code?

Yes, you can customize error handling by monkey-patching the `_handle_unknown_parameters` function in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py). Because Hypster centralizes all error message generation in this single function, you can replace it with a custom implementation that logs to your preferred logging framework, reformats messages for your organization's style guide, or integrates with external monitoring systems. The function signature accepts `values`, `called`, and `policy` parameters, making it straightforward to wrap or extend.

### What happens if I pass parameters that are never accessed in the config function?

When you supply parameters that the configuration function does not access, Hypster detects this mismatch in the `_handle_unknown_parameters` function (lines 73-107 in [`src/hypster/core.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/core.py)). By default, it emits a `UserWarning` listing the unused parameters. If you set `on_unknown="raise"`, it raises a `ValueError` instead. If you set `on_unknown="ignore"`, the parameters are silently discarded. In all cases, Hypster tracks which parameters were actually called using the `HP` class's `original_called_params` and `called_params` attributes.