github/spec-kit · error · ValueError

providers[{i}]: 'auth' must be a non-empty string

Error message

providers[{i}]: 'auth' must be a non-empty string

What it means

Raised when the `auth` field of a `providers` entry is missing, not a string, or empty. The auth scheme string must be present and non-empty because it is checked against the chosen provider's `supported_auth_schemes` right after this guard.

Source

Thrown at src/specify_cli/authentication/config.py:151

            raise ValueError(f"providers[{i}]: each host must be a non-empty string")
        # Normalize hosts: strip whitespace and lowercase
        hosts = [h.strip().lower() for h in hosts]
        # Reject dangerous wildcard forms (e.g. *github.com matches github.com.evil.com)
        for h in hosts:
            if not _is_valid_host_pattern(h):
                raise ValueError(
                    f"providers[{i}]: invalid host pattern {h!r}. "
                    "Only exact hostnames or '*.suffix' forms are allowed "
                    "(e.g. 'github.com' or '*.visualstudio.com')."
                )

        provider = entry_raw.get("provider", "")
        if not isinstance(provider, str) or not provider:
            raise ValueError(f"providers[{i}]: 'provider' must be a non-empty string")

        auth = entry_raw.get("auth", "")
        if not isinstance(auth, str) or not auth:
            raise ValueError(f"providers[{i}]: 'auth' must be a non-empty string")

        token = entry_raw.get("token")
        token_env = entry_raw.get("token_env")

        # Validate token/token_env types
        if token is not None and (not isinstance(token, str) or not token.strip()):
            raise ValueError(f"providers[{i}]: 'token' must be a non-empty string")
        if token_env is not None and (not isinstance(token_env, str) or not token_env.strip()):
            raise ValueError(f"providers[{i}]: 'token_env' must be a non-empty string")

        # Validate provider+scheme compatibility
        from . import get_provider as _get_provider
        _prov = _get_provider(provider)
        if _prov is None:
            from . import AUTH_REGISTRY
            raise ValueError(
                f"providers[{i}]: unknown provider {provider!r}; "
                f"registered: {sorted(AUTH_REGISTRY.keys())}"

View on GitHub (pinned to bf88c9f9a8)

Solutions

  1. Set `auth` to a scheme the provider supports, e.g. `bearer`, `basic-pat`, or `azure-ad`
  2. Fix the key name if you used `scheme`/`auth_scheme`/`type` instead of `auth`
  3. Check the provider's supported schemes in the error that follows this validation

Example fix

# before
- hosts: ["github.com"]
  provider: github
  token_env: GITHUB_TOKEN

# after
- hosts: ["github.com"]
  provider: github
  auth: bearer
  token_env: GITHUB_TOKEN
Defensive patterns

Strategy: validation

Validate before calling

for i, entry in enumerate(raw.get("providers", [])):
    auth = entry.get("auth")
    if not isinstance(auth, str) or not auth:
        raise SystemExit(f"providers[{i}]: missing 'auth' — set bearer/basic-pat/azure-ad")

Type guard

def has_auth_scheme(entry: object) -> bool:
    return isinstance(entry, dict) and isinstance(entry.get("auth"), str) and bool(entry["auth"].strip())

Try / catch

try:
    load_auth_config(raw)
except ValueError as exc:
    if "'auth' must be a non-empty string" in str(exc):
        # prompt the user for a scheme or default to a provider-supported one
        raise
    raise

Prevention

When it happens

Trigger: A provider entry omits the `auth` key, sets it to `""`/`null`, or uses a non-string JSON/YAML value.

Common situations: Minimal config that only sets hosts and token, assuming a default scheme exists (there is none); key named `auth_scheme` or `scheme` by mistake.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/13a4602c53d7c8cc. Report an issue: GitHub.