github/spec-kit · error · ValueError

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

Error message

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

What it means

Raised when a provider entry sets an explicit `token` that is either not a string or blank. `token` is optional (a `token_env` alternative exists), but if present it must be a non-empty, non-whitespace string.

Source

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

                    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())}"
            )
        if auth not in _prov.supported_auth_schemes:
            raise ValueError(
                f"providers[{i}]: provider {provider!r} does not support "
                f"auth scheme {auth!r}; supported: {list(_prov.supported_auth_schemes)}"
            )

View on GitHub (pinned to bf88c9f9a8)

Solutions

  1. Quote the token in YAML/JSON so it is a string, e.g. `token: "1234567890"`
  2. Remove the `token` key entirely if you meant to use `token_env` instead
  3. Ensure any templating step actually produced a value rather than an empty string

Example fix

# before
token: 1234567890abcdef   # parsed as int
token: ""

# after
token: "1234567890abcdef"
Defensive patterns

Strategy: validation

Validate before calling

token = entry.get("token")
if token is not None and (not isinstance(token, str) or not token.strip()):
    raise SystemExit("token must be a non-empty string — quote it in YAML or use token_env")

Type guard

def has_valid_token_source(entry: dict) -> bool:
    token, token_env = entry.get("token"), entry.get("token_env")
    token_ok = token is None or (isinstance(token, str) and token.strip())
    env_ok = token_env is None or (isinstance(token_env, str) and token_env.strip())
    return token_ok and env_ok and (token is not None or token_env is not None)

Try / catch

try:
    load_auth_config(raw)
except ValueError as exc:
    if "'token' must be a non-empty string" in str(exc):
        # quote the value or drop the key in favor of token_env
        raise
    raise

Prevention

When it happens

Trigger: `"token": ""`, `"token": " "`, `"token": null` handled? no — `null` means absent; the trigger is a non-None non-string or whitespace-only value, e.g. `"token": 12345` or `"token": ""`.

Common situations: Pasting a numeric PAT (some providers issue numeric tokens) so YAML parses it as an int; empty string left by an env-substitution placeholder that didn't expand; quoting issues in YAML.

Related errors

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