How to Handle Configuration Errors Gracefully with Custom Messages in Hypster

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). 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) 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) 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) 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:

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).

Raising Exceptions for Unknown Parameters

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

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.

Getting Typo Suggestions

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

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.

Silencing Unknown Parameters

To suppress all warnings and errors for unknown parameters:

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.

Custom Error Handling

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

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	Core instantiate API, unknown‑parameter handling, error‑policy orchestration	core.py
src/hypster/utils.py	Validation of config‑function signatures and helper utilities (e.g., suggest_similar_names)	utils.py
src/hypster/hp.py	Definition of the HP class that tracks called parameters	hp.py
tests/test_error_handling.py	Test suite demonstrating the three policies and typo suggestions	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) 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.

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. 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). 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.

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