Panniantong/Agent-Reach · error · McporterConfigError

mcporter 配置文件无法安全读取

Error message

mcporter 配置文件无法安全读取

What it means

Raised when reading a mcporter config layer raises OSError (EPERM, EACCES, EIO...) or UnicodeError (file not decodable as UTF-8) — i.e. the file exists and passes the symlink/regular-file policy, but the OS read or UTF-8 decode fails. Pure I/O and encoding problems, as opposed to error 10's policy refusals or error 12's missing file.

Source

Thrown at agent_reach/channels/mcporter.py:121

    project_path = root / "config" / "mcporter.json"
    if os.path.lexists(project_path):
        layers.append((project_path, "project"))
    return layers


def _read_config_object(config_path: Path) -> dict:
    try:
        raw = read_small_text_no_follow(
            config_path,
            max_bytes=_MAX_CONFIG_BYTES,
        )
    except PrivatePathError as exc:
        raise McporterConfigError(
            f"mcporter 配置文件无法安全读取：{exc}"
        ) from exc
    except (OSError, UnicodeError) as exc:
        raise McporterConfigError("mcporter 配置文件无法安全读取") from exc
    if raw is None:
        raise McporterConfigError("mcporter 配置文件不存在")
    try:
        payload = json.loads(raw)
    except json.JSONDecodeError as exc:
        raise McporterConfigError("mcporter 配置不是有效的 UTF-8 JSON") from exc
    if not isinstance(payload, dict):
        raise McporterConfigError("mcporter 配置顶层必须是对象")
    return payload


def configured_server_names(output: str) -> set[str]:
    """Return exact configured server names from ``mcporter ... --json``.

    Paths, descriptions, endpoints, and other metadata are deliberately
    ignored: only each server object's ``name`` field is a routing signal.
    """
    try:

View on GitHub (pinned to 93ae1d18c3)

Solutions

1. Re-save the file as UTF-8 (no BOM needed, JSON must be UTF-8 anyway)
2. Fix ownership/permissions: chown $USER file && chmod 644 file
3. If on a network mount, retry from a stable path or copy the file locally
4. Confirm with: file mcporter.json (should say UTF-8/ASCII text)

Example fix

# before: file encoded in GBK with Chinese comments
# after
 iconv -f GBK -t UTF-8 mcporter.json > mcporter.json.utf8 && mv mcporter.json.utf8 mcporter.json

import os

def config_readable_utf8(path) -> bool:
    try:
        with open(path, "rb") as fh:
            data = fh.read(1024 * 1024)
        data.decode("utf-8")
        return True
    except (OSError, UnicodeError):
        return False

except McporterConfigError as exc:
    if isinstance(exc.__cause__, UnicodeError):
        hint = "re-save the config as UTF-8"
    elif isinstance(exc.__cause__, OSError):
        hint = f"fix permissions on the config: {exc.__cause__}"

When it happens

Trigger: File exists but permission denied (chmod 000, different owner); I/O error reading from a failing disk or network mount; file saved in GBK/Latin-1 with non-ASCII bytes so payload.decode('utf-8') raises UnicodeDecodeError.

Common situations: Configs edited on Windows in a legacy codepage; restrictive umask or root-owned file from a sudo-run tool; flaky NFS/FUSE mounts.

Related errors

• mcporter 配置文件无法安全读取：{exc}
• mcporter 配置文件不存在
• mcporter 配置缺少 mcpServers 对象
• mcporter 配置包含无效的 server name
• mcporter server 定义必须是对象

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