HKUDS/DeepTutor · error · HTTPException

Channel config saved but failed to restart listeners ({type(

Error message

Channel config saved but failed to restart listeners ({type(exc).__name__}); try stopping and starting the partner.

What it means

Generic 500 from the channel-onboarding apply endpoint: the channel config was persisted successfully, but restarting the partner's listeners afterward raised an unexpected exception. The exception type name is embedded in the detail.

Source

Thrown at deeptutor/api/routers/partners.py:886

@router.delete("/{partner_id}/channel-onboarding/{session_id}", dependencies=_MANAGEABLE)
async def cancel_partner_channel_onboarding(partner_id: str, session_id: str):
    onboarding, _ = _onboarding_manager_and_partner(partner_id)
    try:
        return await onboarding.cancel(partner_id, session_id)
    except ChannelOnboardingError as exc:
        raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None


@router.post("/{partner_id}/channel-onboarding/{session_id}/apply", dependencies=_MANAGEABLE)
async def apply_partner_channel_onboarding(partner_id: str, session_id: str):
    onboarding, mgr = _onboarding_manager_and_partner(partner_id)
    try:
        return await onboarding.apply(partner_id, session_id, mgr)
    except ChannelOnboardingError as exc:
        raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
    except Exception as exc:
        logger.exception("Failed to apply channel onboarding for '%s'", partner_id)
        raise HTTPException(
            status_code=500,
            detail=(
                "Channel config saved but failed to restart listeners "
                f"({type(exc).__name__}); try stopping and starting the partner."
            ),
        ) from exc


# ── Soul (the partner's own SOUL.md) ───────────────────────────


@router.get("/{partner_id}/soul", dependencies=_MANAGEABLE)
async def get_partner_soul(partner_id: str):
    return {"partner_id": partner_id, "content": read_soul(partner_id)}


@router.put("/{partner_id}/soul", dependencies=_MANAGEABLE)
async def put_partner_soul(partner_id: str, payload: SoulUpdateBody):

View on GitHub (pinned to 3e82f13042)

Solutions

1. Stop and start the partner via the partners API/CLI (as the message suggests)
2. Inspect server logs (logger.exception captured the full traceback) for the root cause
3. Verify channel credentials are still valid and network reachable
4. Restart the backend if listener state is wedged

await fetch(`/api/partners/${id}/status`).then(r=>r.json()); // confirm listener health before apply

catch (e) { if (e.status === 500) { await stopPartner(id); await startPartner(id); } }

When it happens

Trigger: POST .../channel-onboarding/{session_id}/apply succeeds at save time but partner listener restart (connection to Matrix/Discord/etc.) fails with any non-ChannelOnboardingError exception.

Common situations: Expired or revoked bot tokens, network egress blocked, channel service outage, or version drift between config schema and listener code after an upgrade.

Related errors

• Failed to reload channels: {type(exc).__name__}
• Channel onboarding provider request failed ({type(exc).__nam
• str(exc)
• {str(e)}
• t("api.partner_not_found_or_not_running")

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