CoplayDev/unity-mcp · error · ValueError

PluginHub session missing required 'project' or 'hash' field

Error message

PluginHub session missing required 'project' or 'hash' fields.

What it means

Raised by the unity_instances MCP resource when iterating over WebSocket sessions from PluginHub and a SessionDetails entry has a falsy project or hash field. SessionDetails (transport/models.py:60) declares project and hash as required str fields, so Pydantic should enforce non-empty strings at parse time — but the guard also catches empty-string values ('' is falsy) that pass Pydantic's str validation. This indicates a Unity plugin registered a session with incomplete handshake data.

Source

Thrown at Server/src/services/resources/unity_instances.py:54

    await ctx.info("Listing Unity instances")

    try:
        transport = (config.transport_mode or "stdio").lower()
        if transport == "http":
            # HTTP/WebSocket transport: query PluginHub
            # In remote-hosted mode, filter sessions by user_id
            user_id = (await ctx.get_state(
                "user_id")) if config.http_remote_hosted else None
            sessions_data = await PluginHub.get_sessions(user_id=user_id)
            sessions = sessions_data.sessions

            instances = []
            for session_id, session_info in sessions.items():
                project = session_info.project
                project_hash = session_info.hash

                if not project or not project_hash:
                    raise ValueError(
                        "PluginHub session missing required 'project' or 'hash' fields."
                    )

                instances.append({
                    "id": f"{project}@{project_hash}",
                    "name": project,
                    "hash": project_hash,
                    "unity_version": session_info.unity_version,
                    "connected_at": session_info.connected_at,
                    "session_id": session_id,
                })

            # Check for duplicate project names
            name_counts = {}
            for inst in instances:
                name_counts[inst["name"]] = name_counts.get(
                    inst["name"], 0) + 1

View on GitHub (pinned to c21bf496bc)

Solutions

1. Update the MCP for Unity package in the Unity Editor to match the server version — older plugins may not send the hash field.
2. Restart the Unity Editor so it re-registers its session with a complete handshake.
3. If persistent, clear the PluginHub session store (check for a sessions cache/state file) and reconnect.
4. Report the session_id from server logs to identify which Unity instance sent incomplete data.

# Validate session data before building instances list
for session_id, session_info in sessions.items():
    project = getattr(session_info, "project", None)
    project_hash = getattr(session_info, "hash", None)
    if not project or not project_hash:
        # Skip incomplete sessions instead of raising, or log for investigation
        logger.warning("Skipping incomplete session %s: project=%r hash=%r", session_id, project, project_hash)
        continue

from transport.models import SessionDetails

def is_complete_session(s: SessionDetails) -> bool:
    return bool(getattr(s, "project", None)) and bool(getattr(s, "hash", None))

When it happens

Trigger: A Unity Editor connected via WebSocket and sent a session registration message with empty project name or empty hash; a race condition where the session was registered mid-handshake before the project path was resolved; a corrupt or partial PluginHub session store after a server crash; an older Unity plugin version that does not send the hash field.

Common situations: Unity plugin version mismatch (older plugin omits hash); a Unity project whose path could not be hashed (permissions, unusual path); PluginHub state deserialized from a stale/corrupt store after an unclean shutdown; a transient registration race during rapid connect/disconnect.

Related errors

• OpenClaw config contains non-JSON content and cannot be safe
• Color array must have 3 or 4 elements.
• Port must be positive.
• Port {port} is already in use.
• uid required

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