usestrix/strix · error · ValueError

Unknown command: {command}

Error message

Unknown command: {command}

What it means

Raised by the TUI backend controller's command dispatch (strix/interface/tui/backend/controller.py:277) when a command string is not one of the eight registered handlers (setup.add_target, setup.set_instruction, setup.start, setup.confirm_mount, agent.send_message, agent.stop, viewer.open, app.quit). It signals a frontend/backend protocol mismatch: the Go/Bubble Tea frontend sent a command name this Python controller version does not know.

Source

Thrown at strix/interface/tui/backend/controller.py:277

        next_cursor, events = self.live_view.event_changes_since(cursor)
        return next_cursor, [
            collection_item_projection(event) for event in events[-MAX_TERMINAL_EVENTS:]
        ]

    async def handle(self, command: str, payload: dict[str, Any]) -> dict[str, Any]:
        handlers = {
            "setup.add_target": self._add_target,
            "setup.set_instruction": self._set_instruction,
            "setup.start": self._start,
            "setup.confirm_mount": self._confirm_mount,
            "agent.send_message": self._send_message,
            "agent.stop": self._stop_agent,
            "viewer.open": self._open_viewer,
            "app.quit": self._quit,
        }
        handler = handlers.get(command)
        if handler is None:
            raise ValueError(f"Unknown command: {command}")
        result = await handler(payload)
        self.notify_changed()
        return result

    async def _add_target(self, payload: dict[str, Any]) -> dict[str, Any]:
        self._require_setup_mutable()
        target = self._required_string(payload, "target")
        if target not in self.targets:
            self.targets.append(target)
        return {"target": target, "total": len(self.targets)}

    async def _set_instruction(self, payload: dict[str, Any]) -> dict[str, Any]:
        self._require_setup_mutable()
        instruction = payload.get("instruction", "")
        if not isinstance(instruction, str):
            raise TypeError("instruction must be a string")
        self.instruction = instruction.strip()
        return {"instruction": self.instruction}

View on GitHub (pinned to 8551339130)

Solutions

1. Reinstall/align both halves of the TUI to the same version (make dev-install or a fresh pip/uv install) so frontend and backend share one command set.
2. If driving the controller programmatically, restrict sends to the registered handlers listed in the dispatch table.
3. Check the release notes/diff for renamed commands and update the caller accordingly.

Example fix

# before
await controller.handle("setup.addTarget", {})   # Unknown command

# after
await controller.handle("setup.add_target", {})

KNOWN = {"setup.add_target", "setup.set_instruction", "setup.start",
         "setup.confirm_mount", "agent.send_message", "agent.stop",
         "viewer.open", "app.quit"}
if command not in KNOWN:
    raise ValueError(f'unsupported command: {command}')

def is_known_command(command: str) -> bool:
    KNOWN = {"setup.add_target", "setup.set_instruction", "setup.start",
             "setup.confirm_mount", "agent.send_message", "agent.stop",
             "viewer.open", "app.quit"}
    return command in KNOWN

try:
    await controller.handle(command, payload)
except ValueError as exc:
    if 'Unknown command' in str(exc):
        logging.error('protocol mismatch: upgrade TUI frontend/backend to same version')
        raise SystemExit(1)
    raise

When it happens

Trigger: A TUI frontend and backend built from different Strix versions (stale installed binary vs updated Python package); hand-written websocket/bridge clients sending arbitrary command names; renamed/removed commands after an upgrade.

Common situations: Upgrading the Python package while an old compiled Go TUI binary remains on PATH (or vice versa); development against the controller with experimental command names; protocol drift after pulling main.

Related errors

• The interactive interface could not start: {exc}
• instruction must be a string
• Scan is already starting or running
• verify must be a boolean
• mount_working_dir must be a boolean

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/1625543286f185dc. Report an issue: GitHub.