HKUDS/DeepTutor · error · HTTPException

A partner_id is required to connect a partner.

Error message

A partner_id is required to connect a partner.

What it means

Connections whose agent_kind is the partner backend must include a non-empty partner_id; partners are pre-provisioned and referenced by id, unlike CLI agents.

Source

Thrown at deeptutor/api/routers/subagents.py:153

    A partner connection (``agent_kind == "partner"``) binds a ``partner_id``
    instead of a working directory: consulting it opens a fresh session on that
    partner, exactly as if the user started one from the partner page. Every
    consult within one DeepTutor chat lands in that one partner session.
    """
    name = (payload.name or "").strip()
    agent_kind = (payload.agent_kind or "").strip()
    if not name or not agent_kind:
        raise HTTPException(status_code=400, detail="Both name and agent_kind are required.")
    if agent_kind not in list_backend_kinds():
        raise HTTPException(status_code=400, detail=f"Unknown agent kind: {agent_kind!r}")

    resolved_cwd = ""
    partner_id = ""
    if agent_kind == PARTNER_BACKEND_KIND:
        partner_id = (payload.partner_id or "").strip()
        if not partner_id:
            raise HTTPException(
                status_code=400, detail="A partner_id is required to connect a partner."
            )
        # Partners are admin-managed, but an admin can assign one to a user via
        # the grant system. An admin may connect any partner; a non-admin only a
        # partner assigned to them (403 otherwise). The partner still runs in its
        # own isolated scope — connecting just lets the user consult it in chat.
        assert_partner_allowed(partner_id)
        from deeptutor.services.partners import get_partner_manager

        if not get_partner_manager().partner_exists(partner_id):
            raise HTTPException(status_code=400, detail=f"No partner named {partner_id!r}.")
    else:
        raw_cwd = (payload.cwd or "").strip()
        if raw_cwd:
            try:
                resolved_cwd = str(assert_path_allowed(raw_cwd))
            except ValueError as exc:
                raise HTTPException(status_code=400, detail=str(exc)) from exc

View on GitHub (pinned to 3e82f13042)

Solutions

1. Include the partner_id from the partner listing in the payload
2. Ensure the UI requires partner selection when agent_kind is the partner kind
3. Verify the partner exists via the partners endpoint before connecting

Example fix

// before
{"name":"tutor","agent_kind":"partner"}
// after
{"name":"tutor","agent_kind":"partner","partner_id":"math-buddy"}

if (agentKind === 'partner' && !partnerId?.trim()) {
  showPartnerRequired(); return;
}

const needsPartnerId = (kind: string) => kind === 'partner';

When it happens

Trigger: POST /connections with agent_kind == PARTNER_BACKEND_KIND and partner_id missing, null, or whitespace.

Common situations: Reusing the CLI-connection form for partners without a partner selector; partner id copied with trailing spaces; frontend never sends partner_id.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• No partner named {partner_id!r}.
• Unknown agent kind: {kind!r}
• Both name and agent_kind are required.
• Unknown agent kind: {agent_kind!r}
• {exc}

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