rohitg00/ai-engineering-from-scratch · error · ValueError

runtime discovery failed

Error message

runtime discovery failed

What it means

Runtime verification failure in Registry.register: after static document validation passes, the registry probes the live server's discovery endpoints and the probe failed (endpoints unreachable, response mismatch, or serverInfo.version drift). The entry is rejected because the registry only lists servers it could verify at runtime.

Solutions

1. Start the MCP server and confirm its discovery endpoint is reachable before registering
2. Align serverInfo.version with the version in server.json
3. Retry registration once transient network failures clear
4. Inspect the collected runtime_discovery report for the specific failing check

When it happens

Trigger: Thrown at phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py:431 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of rohitg00/ai-engineering-from-scratch@39ea8a1c6d (2026-08-26). Data as JSON: /api/errors/5e21a505ac3439fc. Report an issue: GitHub.

Appendix: source

Thrown at phases/19-capstone-projects/13-mcp-server-with-registry/code/main.py:431

        issues.append("runtime serverInfo.version does not match server.json version")
    return issues


@dataclass
class Registry:
    publisher_domain: str = PUBLISHER_DOMAIN
    entries: dict[str, dict] = field(default_factory=dict)
    runtime_discovery: dict[str, dict] = field(default_factory=dict)

    def register(self, server: MCPServer) -> None:
        document = server.registry_document()
        issues = validate_registry_document(document)
        issues.extend(validate_publisher_namespace(document, self.publisher_domain))
        if issues:
            raise ValueError("; ".join(issues))
        discovery = server.discover(request_meta())
        if "error" in discovery:
            raise ValueError("runtime discovery failed")
        alignment_issues = validate_runtime_alignment(document, discovery)
        if alignment_issues:
            raise ValueError("; ".join(alignment_issues))
        self.entries[server.name] = deepcopy(document)
        self.runtime_discovery[server.name] = deepcopy(discovery)

    def search(self, query: str) -> list[str]:
        needle = query.casefold()
        return sorted(
            name
            for name, entry in self.entries.items()
            if needle in name.casefold()
            or needle in entry["title"].casefold()
            or needle in entry["description"].casefold()
        )


def build_readonly_server() -> MCPServer:

View on GitHub (pinned to 39ea8a1c6d)