{"record":{"id":"4f8fae36848c5dd9","repo":"HKUDS/DeepTutor","slug":"channel-config-saved-but-failed-to-restart-listene","errorCode":null,"errorMessage":"Channel config saved but failed to restart listeners ({type(exc).__name__}); try stopping and starting the partner.","messagePattern":"Channel config saved but failed to restart listeners \\((.+?)\\); try stopping and starting the partner\\.","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"deeptutor/api/routers/partners.py","lineNumber":886,"sourceCode":"@router.delete(\"/{partner_id}/channel-onboarding/{session_id}\", dependencies=_MANAGEABLE)\nasync def cancel_partner_channel_onboarding(partner_id: str, session_id: str):\n    onboarding, _ = _onboarding_manager_and_partner(partner_id)\n    try:\n        return await onboarding.cancel(partner_id, session_id)\n    except ChannelOnboardingError as exc:\n        raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None\n\n\n@router.post(\"/{partner_id}/channel-onboarding/{session_id}/apply\", dependencies=_MANAGEABLE)\nasync def apply_partner_channel_onboarding(partner_id: str, session_id: str):\n    onboarding, mgr = _onboarding_manager_and_partner(partner_id)\n    try:\n        return await onboarding.apply(partner_id, session_id, mgr)\n    except ChannelOnboardingError as exc:\n        raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None\n    except Exception as exc:\n        logger.exception(\"Failed to apply channel onboarding for '%s'\", partner_id)\n        raise HTTPException(\n            status_code=500,\n            detail=(\n                \"Channel config saved but failed to restart listeners \"\n                f\"({type(exc).__name__}); try stopping and starting the partner.\"\n            ),\n        ) from exc\n\n\n# ── Soul (the partner's own SOUL.md) ───────────────────────────\n\n\n@router.get(\"/{partner_id}/soul\", dependencies=_MANAGEABLE)\nasync def get_partner_soul(partner_id: str):\n    return {\"partner_id\": partner_id, \"content\": read_soul(partner_id)}\n\n\n@router.put(\"/{partner_id}/soul\", dependencies=_MANAGEABLE)\nasync def put_partner_soul(partner_id: str, payload: SoulUpdateBody):","sourceCodeStart":868,"sourceCodeEnd":904,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/partners.py#L868-L904","documentation":"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.","triggerScenarios":"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.","commonSituations":"Expired or revoked bot tokens, network egress blocked, channel service outage, or version drift between config schema and listener code after an upgrade.","solutions":["Stop and start the partner via the partners API/CLI (as the message suggests)","Inspect server logs (logger.exception captured the full traceback) for the root cause","Verify channel credentials are still valid and network reachable","Restart the backend if listener state is wedged"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"await fetch(`/api/partners/${id}/status`).then(r=>r.json()); // confirm listener health before apply","typeGuard":null,"tryCatchPattern":"catch (e) { if (e.status === 500) { await stopPartner(id); await startPartner(id); } }","preventionTips":["Keep channel tokens fresh","Ensure network egress to the channel service","After apply fails with 500, retry with stop/start as the message suggests"],"tags":["partners","onboarding","restart","http-500"],"backgroundTag":"service-restart-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}