What causes "gh hosts.yml 的 users 配置无效" in Panniantong/Agent-Reach?

Remove the 'users' key entirely if you only use oauth_token/user (it is optional for this check)

Panniantong/Agent-Reach · error · GitHubConfigError

gh hosts.yml 的 users 配置无效

Error message

gh hosts.yml 的 users 配置无效

What it means

Raised when the github.com host entry's 'users' key exists but is not a mapping. gh writes 'users:' as a map of login names to metadata; a list or scalar there is treated as corrupt configuration.

Source

Thrown at agent_reach/channels/github.py:80

        return False
    try:
        payload = yaml.safe_load(raw)
    except yaml.YAMLError as exc:
        raise GitHubConfigError("gh hosts.yml 不是有效的 UTF-8 YAML") from exc
    if payload is None:
        return False
    if not isinstance(payload, dict):
        raise GitHubConfigError("gh hosts.yml 顶层必须是对象")

    host = payload.get("github.com")
    if host is None:
        return False
    if not isinstance(host, dict):
        raise GitHubConfigError("gh hosts.yml 的 github.com 配置无效")

    users = host.get("users")
    if users is not None and not isinstance(users, dict):
        raise GitHubConfigError("gh hosts.yml 的 users 配置无效")
    return bool(host.get("oauth_token") or host.get("user") or users)


def _explicit_github_credentials(config) -> bool:
    if any(os.environ.get(name) for name in ("GH_TOKEN", "GITHUB_TOKEN")):
        return True
    if config is None:
        return False
    try:
        return bool(config.get("github_token"))
    except Exception as exc:
        raise GitHubConfigError("Agent Reach 的 GitHub 配置无法读取") from exc


class GitHubChannel(Channel):
    name = "github"
    description = "GitHub 仓库和代码"
    backends = ["gh CLI"]

View on GitHub (pinned to 93ae1d18c3)

Solutions

Remove the 'users' key entirely if you only use oauth_token/user (it is optional for this check)
Rewrite users as a mapping: 'users:\n alice: {}'
Regenerate with `gh auth login` to get gh's current canonical format

Example fix

# before
 github.com:
   oauth_token: gho_x
   users: [alice]
# after
 github.com:
   oauth_token: gho_x
   user: alice

Defensive patterns

Strategy: validation

Validate before calling

import yaml

def users_entry_valid(path) -> bool:
    try:
        d = yaml.safe_load(open(path, encoding="utf-8").read()) or {}
        host = d.get("github.com") or {}
    except Exception:
        return False
    users = host.get("users")
    return users is None or isinstance(users, dict)

Try / catch

except GitHubConfigError as exc:
    log(f"gh users block malformed: {exc}")
    treat_github_as_unconfigured()

Prevention

Omit the users key unless gh itself wrote it
Keep gh's canonical structure; let gh own the file
Check `gh auth status` output matches expectations after manual edits

When it happens

Trigger: hosts.yml github.com block contains 'users: []' (empty list), 'users: someuser', or 'users:\n- a'. users is not None and not a dict → error. Absent 'users' key or a proper dict is fine.

Common situations: Hand-crafted hosts.yml following an outdated gh format; older gh versions or forks writing a different users shape; YAML shortcut ('users: [alice]') from copy-paste.

Related errors

AI-assisted analysis of Panniantong/Agent-Reach@93ae1d18c3 (2026-08-14). Data as JSON: /api/errors/b0ff657c45f81dd1. Report an issue: GitHub.