What causes "Invalid UNITY_MCP_HTTP_PORT value: {port_raw!r}" in CoplayDev/unity-mcp?

Set UNITY_MCP_HTTP_PORT to a plain integer (e.g. 8080).

CoplayDev/unity-mcp · error · ValueError

Invalid UNITY_MCP_HTTP_PORT value: {port_raw!r}

Error message

Invalid UNITY_MCP_HTTP_PORT value: {port_raw!r}

What it means

Thrown by CLIConfig.from_env() when the UNITY_MCP_HTTP_PORT environment variable cannot be parsed as an int. The value defaults to '8080' only when unset; if set to a non-numeric string, int() raises and this ValueError propagates. It fires during CLI startup, before any network call.

Source

Thrown at Server/src/cli/utils/config.py:24


@dataclass
class CLIConfig:
    """Configuration for CLI connection to Unity."""

    host: str = "127.0.0.1"
    port: int = 8080
    timeout: int = 30
    format: str = "text"  # text, json, table
    unity_instance: Optional[str] = None

    @classmethod
    def from_env(cls) -> "CLIConfig":
        port_raw = os.environ.get("UNITY_MCP_HTTP_PORT", "8080")
        try:
            port = int(port_raw)
        except (ValueError, TypeError):
            raise ValueError(
                f"Invalid UNITY_MCP_HTTP_PORT value: {port_raw!r}")

        timeout_raw = os.environ.get("UNITY_MCP_TIMEOUT", "30")
        try:
            timeout = int(timeout_raw)
        except (ValueError, TypeError):
            raise ValueError(
                f"Invalid UNITY_MCP_TIMEOUT value: {timeout_raw!r}")

        return cls(
            host=os.environ.get("UNITY_MCP_HOST", "127.0.0.1"),
            port=port,
            timeout=timeout,
            format=os.environ.get("UNITY_MCP_FORMAT", "text"),
            unity_instance=os.environ.get("UNITY_MCP_INSTANCE"),
        )

View on GitHub (pinned to c21bf496bc)

Solutions

Set UNITY_MCP_HTTP_PORT to a plain integer (e.g. 8080).
Unset the variable to fall back to the default 8080: `unset UNITY_MCP_HTTP_PORT`.
Audit .env / shell profiles for a stale or empty UNITY_MCP_HTTP_PORT assignment.

Example fix

# before
export UNITY_MCP_HTTP_PORT=8080/tcp
# after
export UNITY_MCP_HTTP_PORT=8080

Defensive patterns

Strategy: validation

Validate before calling

raw = os.environ.get("UNITY_MCP_HTTP_PORT", "8080")
if not raw.isdigit():
    raise ValueError(f"Invalid UNITY_MCP_HTTP_PORT value: {raw!r}")
port = int(raw)

Type guard

def is_int_env(raw: str | None) -> bool:
    return raw is not None and raw.lstrip("+").isdigit()

Try / catch

try:
    cfg = CLIConfig.from_env()
except ValueError as e:
    print_error(str(e)); sys.exit(1)

Prevention

Keep UNITY_MCP_HTTP_PORT a bare integer in env files.
Avoid unit suffixes and empty values.

When it happens

Trigger: Setting UNITY_MCP_HTTP_PORT to a non-integer such as 'abc', '8080/tcp', '' (empty), or '80.0'. Also when a value with surrounding whitespace is supplied on some shells.

Common situations: A misconfigured .env file or shell profile exports a port with a unit suffix or typo, or an empty value from an unset-in-template variable. Common when port is templated and the template variable resolved to blank.

Related errors

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/7dafd24af3b5b9cd. Report an issue: GitHub.