ruvnet/RuView · error · ValueError

Invalid unwrapping method: {config['unwrapping_method']}. Mu

Error message

Invalid unwrapping method: {config['unwrapping_method']}. Must be one of {valid_methods}

What it means

Raised by PhaseSanitizer._validate_config when unwrapping_method is present but not one of the allowed strings 'numpy', 'scipy', 'custom'. The message lists both the invalid value and the valid set, so it is self-diagnosing. This fires at construction time, before any phase data is processed.

Source

Thrown at archive/v1/src/core/phase_sanitizer.py:68

    def _validate_config(self, config: Dict[str, Any]) -> None:
        """Validate configuration parameters.
        
        Args:
            config: Configuration to validate
            
        Raises:
            ValueError: If configuration is invalid
        """
        required_fields = ['unwrapping_method', 'outlier_threshold', 'smoothing_window']
        missing_fields = [field for field in required_fields if field not in config]
        
        if missing_fields:
            raise ValueError(f"Missing required configuration: {missing_fields}")
        
        # Validate unwrapping method
        valid_methods = ['numpy', 'scipy', 'custom']
        if config['unwrapping_method'] not in valid_methods:
            raise ValueError(f"Invalid unwrapping method: {config['unwrapping_method']}. Must be one of {valid_methods}")
        
        # Validate thresholds
        if config['outlier_threshold'] <= 0:
            raise ValueError("outlier_threshold must be positive")
        
        if config['smoothing_window'] <= 0:
            raise ValueError("smoothing_window must be positive")
    
    def unwrap_phase(self, phase_data: np.ndarray) -> np.ndarray:
        """Unwrap phase data to remove discontinuities.
        
        Args:
            phase_data: Wrapped phase data (2D array)
            
        Returns:
            Unwrapped phase data
            
        Raises:

View on GitHub (pinned to 4685618388)

Solutions

1. Use exactly one of: 'numpy', 'scipy', or 'custom'.
2. Normalize case before construction: `config['unwrapping_method'] = config['unwrapping_method'].lower()` (after confirming the value is a string).
3. If you do not want unwrapping, skip calling unwrap_phase rather than inventing a method name.
4. Pin the allowed set in a constant shared by config generators and tests.

Example fix

# before
sanitizer = PhaseSanitizer({'unwrapping_method': 'Numpy', 'outlier_threshold': 3.0, 'smoothing_window': 5})
# ValueError: Invalid unwrapping method: Numpy. Must be one of ['numpy', 'scipy', 'custom']

# after
sanitizer = PhaseSanitizer({'unwrapping_method': 'numpy', 'outlier_threshold': 3.0, 'smoothing_window': 5})

VALID_METHODS = ('numpy', 'scipy', 'custom')

def normalized_method(value) -> str:
    v = str(value).strip().lower()
    if v not in VALID_METHODS:
        raise ValueError(f'unwrapping_method must be one of {VALID_METHODS}, got {value!r}')
    return v

config['unwrapping_method'] = normalized_method(config['unwrapping_method'])

from typing import TypeGuard

VALID_METHODS = ('numpy', 'scipy', 'custom')

def is_valid_unwrap_method(value: object) -> TypeGuard[str]:
    return isinstance(value, str) and value in VALID_METHODS

try:
    sanitizer = PhaseSanitizer(config)
except ValueError as e:
    if 'Invalid unwrapping method' in str(e):
        config['unwrapping_method'] = 'numpy'
        sanitizer = PhaseSanitizer(config)
    else:
        raise

When it happens

Trigger: Constructing PhaseSanitizer with unwrapping_method set to anything else: 'np', 'numpy.unwrap', 'scipy_unwrap', 'NONE', 'Numpy' (case-sensitive), or None. Case mismatch is the most common variant because the whitelist is lowercase.

Common situations: Abbreviations or fully-qualified function names used instead of the short alias; config generated from an enum whose serialization differs ('UnwrapMethod.NUMPY'); case differences from user-edited YAML; copy-paste from docs of a different version listing different method names; None used to skip unwrapping (not supported — there is no 'none' method).

Related errors

• Missing required configuration: {missing_fields}
• outlier_threshold must be positive
• smoothing_window must be positive
• Threshold must be between 0.0 and 1.0
• FPS must be between 1 and 60

AI-assisted analysis of ruvnet/RuView@4685618388 (2026-08-16). Data as JSON: /api/errors/bfa97fee92c90d5d. Report an issue: GitHub.