github/spec-kit · error · ValueError

auth.json must contain a 'providers' array

Error message

auth.json must contain a 'providers' array

What it means

After confirming auth.json is a JSON object, the loader requires its 'providers' key to be present and to be a list. A missing key (raw.get returns None), a null value, or a non-list value (object, string, number) raises ValueError('auth.json must contain a \'providers\' array').

Source

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

                warnings.warn(
                    f"{config_path} is readable by group/others. "
                    "Consider restricting with: chmod 600 "
                    f"{config_path}",
                    UserWarning,
                    stacklevel=2,
                )
        except OSError:
            pass  # stat failed — skip permission check

    raw = json.loads(config_path.read_text(encoding="utf-8"))

    if not isinstance(raw, dict):
        raise ValueError(f"auth.json must be a JSON object, got {type(raw).__name__}")

    providers_raw = raw.get("providers")
    if not isinstance(providers_raw, list):
        raise ValueError("auth.json must contain a 'providers' array")

    entries: list[AuthConfigEntry] = []
    for i, entry_raw in enumerate(providers_raw):
        if not isinstance(entry_raw, dict):
            raise ValueError(f"providers[{i}]: must be a JSON object")

        hosts = entry_raw.get("hosts")
        if not isinstance(hosts, list) or not hosts:
            raise ValueError(f"providers[{i}]: 'hosts' must be a non-empty array")
        if not all(isinstance(h, str) and h.strip() for h in hosts):
            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}. "

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Ensure the top level is exactly {"providers": [ ... ]} with providers as a JSON array.
2. Fix key typos: 'provider', 'Providers', 'entries' are not recognized — only 'providers'.
3. Validate with jq: jq '.providers | type' auth.json must print "array".

Example fix

// before
{ "providers": { "github": {"hosts": ["github.com"]} } }
// after
{ "providers": [ {"hosts": ["github.com"], "provider": "github", "auth": "bearer"} ] }

import json
from pathlib import Path

raw = json.loads(Path("auth.json").read_text(encoding="utf-8"))
assert isinstance(raw, dict) and isinstance(raw.get("providers"), list), (
    "auth.json must be {\"providers\": [...]}"
)

from typing import Any

def has_providers_array(raw: Any) -> bool:
    """True when raw is an object whose 'providers' is a list."""
    return isinstance(raw, dict) and isinstance(raw.get("providers"), list)

try:
    entries = load_auth_config(path)
except ValueError as exc:
    if "'providers' array" in str(exc):
        raise SystemExit(f"fix auth.json shape: {exc}") from exc
    raise

When it happens

Trigger: auth.json like {"provider": [...]} (singular key typo), {"providers": {"github": ...}} (object instead of array), {} with the key omitted entirely, or "providers": null.

Common situations: Renaming the key during a config cleanup; authoring the file from memory and using a mapping keyed by provider name; schema drift between an internal tool that writes providers as an object and this reader's array contract.

Related errors

• providers[{i}]: must be a JSON object
• providers[{i}]: 'hosts' must be a non-empty array
• auth.json must be a JSON object, got {type(raw).__name__}
• providers[{i}]: each host must be a non-empty string
• AzureDevOpsAuth does not support auth scheme {auth_scheme!r}

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