HKUDS/DeepTutor · error · ValueError

Unknown capability `{requested}`. Available: {available}

Error message

Unknown capability `{requested}`. Available: {available}

What it means

ChatOrchestrator's facade could not resolve the requested capability name against the registered capability manifests. It matches against each manifest's canonical `name` and its `cli_aliases`; a miss raises ValueError listing every registered capability.

Source

Thrown at deeptutor/app/facade.py:75

    """Facade around runtime, session, notebook, and capability contracts."""

    def __init__(self) -> None:
        self.runtime = get_turn_runtime_manager()
        self.store = get_session_store()
        self.notebooks = get_notebook_manager()
        self.capabilities = get_capability_registry()

    def resolve_capability(self, value: str | None) -> str:
        requested = str(value or "chat").strip() or "chat"
        manifests = self.capabilities.get_manifests()
        for manifest in manifests:
            if manifest["name"] == requested:
                return requested
            aliases = {str(alias).strip() for alias in manifest.get("cli_aliases", [])}
            if requested in aliases:
                return str(manifest["name"])
        available = ", ".join(sorted(manifest["name"] for manifest in manifests))
        raise ValueError(f"Unknown capability `{requested}`. Available: {available}")

    def get_capability_contracts(self) -> list[dict[str, Any]]:
        contracts = []
        for manifest in self.capabilities.get_manifests():
            contracts.append(
                {
                    **manifest,
                    "availability": self.get_capability_availability(manifest["name"]).__dict__,
                }
            )
        return contracts

    def get_capability_contract(self, value: str) -> dict[str, Any]:
        resolved = self.resolve_capability(value)
        for manifest in self.capabilities.get_manifests():
            if manifest["name"] == resolved:
                return {
                    **manifest,

View on GitHub (pinned to 3e82f13042)

Solutions

1. Check the error's 'Available:' list and use one of those exact names
2. Use `app.get_capability_contracts()` to enumerate valid names and aliases programmatically
3. If the capability should exist, verify the plugin/entry point registered correctly at bootstrap
4. For custom capabilities, confirm the manifest's `name` field and `cli_aliases` spelling

Example fix

// before
contract = app.get_capability_contract("deep_solve_v2")

// after
contract = app.get_capability_contract("deep_solve")  # canonical name from Available: list

valid = {m["name"] for m in app.get_capability_contracts()} |
       {a for m in app.get_capability_contracts() for a in m.get("cli_aliases", [])}
if requested not in valid:
    raise SystemExit(f"unknown capability {requested!r}; choose from {sorted(valid)}")

def is_known_capability(app, name: str) -> bool:
    contracts = app.get_capability_contracts()
    return any(
        c["name"] == name or name in c.get("cli_aliases", []) for c in contracts
    )

try:
    resolved = app.resolve_capability(name)
except ValueError as exc:
    # message already lists available capabilities
    print(exc); sys.exit(2)

When it happens

Trigger: Calling `app.resolve_capability(name)` (directly or via `get_capability_contract`, `get_capability_availability`, `start_turn`) with a string that is neither a registered manifest name nor one of its `cli_aliases` — e.g. typos ('deepsovle'), removed/renamed capabilities, or a plugin whose registration failed at startup.

Common situations: Upgrading DeepTutor after a capability was renamed; using a stale capability name from old docs; a custom capability plugin failing to register so its name never appears in the registry; passing 'guided-learning' when only the alias table maps some names.

Related errors

• Capability not found: {resolved}
• Model not configured for agent {self.agent_name}. Please act
• Render failed because local LaTeX is missing. Please avoid T
• Document not found
• Unsupported import source: {value!r}

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/b0d8f49770a72db2. Report an issue: GitHub.