NousResearch/hermes-agent · error · ValueError

Transcription provider .name must be a non-empty string

Error message

Transcription provider .name must be a non-empty string

What it means

ValueError from TranscriptionProviderRegistry.register_provider() (agent/transcription_registry.py:79) when provider.name is not a non-empty string after strip(). The name is the registry key (normalized via name.strip().lower()), so an empty name would make the provider unreachable and collide with other empty-named entries.

Source

Thrown at agent/transcription_registry.py:79

    Rejects:

    - Non-:class:`TranscriptionProvider` instances (raises :class:`TypeError`).
    - Empty/whitespace ``.name`` (raises :class:`ValueError`).
    - Names colliding with a built-in (logs a warning, silently
      ignores — built-ins-always-win invariant).

    Re-registration (same ``name``) overwrites the previous entry and
    logs a debug message — makes hot-reload scenarios (tests, dev
    loops) behave predictably.
    """
    if not isinstance(provider, TranscriptionProvider):
        raise TypeError(
            f"register_provider() expects a TranscriptionProvider instance, "
            f"got {type(provider).__name__}"
        )
    name = provider.name
    if not isinstance(name, str) or not name.strip():
        raise ValueError("Transcription provider .name must be a non-empty string")
    key = name.strip().lower()
    if key in _BUILTIN_NAMES:
        logger.warning(
            "Transcription provider '%s' shadows a built-in name; registration "
            "ignored. Built-in STT providers (%s) always win — pick a different "
            "name.",
            key, ", ".join(sorted(_BUILTIN_NAMES)),
        )
        return
    with _lock:
        target = _providers if scope is None else _scoped_providers.setdefault(scope, {})
        existing = target.get(key)
        target[key] = provider
    if existing is not None:
        logger.debug(
            "Transcription provider '%s' re-registered (was %r)",
            key, type(existing).__name__,
        )

View on GitHub (pinned to c896c09c42)

Solutions

  1. Set a concrete name on the provider instance/class before register_provider().
  2. If the name comes from config, validate/fail earlier at plugin load with a clear message about the missing key.
  3. Add an assertion or test that the provider exposes a non-empty string name.

Example fix

# before
class MyProvider(TranscriptionProvider):
    name = ''  # never set -> ValueError on register

# after
class MyProvider(TranscriptionProvider):
    name = 'my-stt'
Defensive patterns

Strategy: validation

Validate before calling

def has_valid_provider_name(provider) -> bool:
    name = getattr(provider, "name", None)
    return isinstance(name, str) and bool(name.strip())

Try / catch

try:
    register_provider(provider)
except ValueError as exc:
    raise ConfigError(f"stt provider misconfigured: {exc}") from exc

Prevention

When it happens

Trigger: Registering a provider whose .name attribute is '', ' ', None, or a non-string (the isinstance check catches both) — e.g. the name was meant to come from config and config was missing, or a dataclass default of empty string was never overwritten.

Common situations: Provider name sourced from a config key that is absent (falls back to ''); copy-pasted provider skeleton with name = '' placeholder; name accidentally assigned to a property that returns None.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/0c5a9986b757c6c6. Report an issue: GitHub.