LiveKit Agent job 시작 실패
configRef를 가진 참가자 부재
마지막 업데이트 2026-10-28
1. 코드 경로
| PPI 저장소 상대 경로 | 역할 |
|---|---|
| apps/livekit-agent/agent.py · ppi_agent (L5506~) | job entrypoint. 가장 먼저 _fetch_model_config(ctx.room.name)을 호출. 예외 시 job 전체 종료. |
| apps/livekit-agent/agent.py · _fetch_model_config (L412~466) | list_participants로 room 참가자를 조회하고, metadata의 configRef로 Valkey 설정 스냅샷을 읽음. 못 찾으면 RuntimeError("LiveKit valkey model config metadata was not found"). |
| apps/livekit-agent/agent.py · ModelConfigParticipantMissingError (L400~) · ppi_agent except (L5513~) | 수정(로컬): metadata 보유 참가자가 없으면 전용 예외를 올리고, entrypoint가 WARN 로그 후 request_shutdown("model_config_participant_missing")으로 정상 종료. |
| apps/web/lib/voice-agent/livekit-token.ts · createLiveKitParticipantToken (L90~123) | 같은 metadata(configRef)를 참가자 토큰 metadata와 RoomAgentDispatch metadata 두 곳에 넣음. |
2. 판정 요약
could not restart participant로 거부됐지만, 토큰의 RoomAgentDispatch로 job만 배정됐다. configRef 형식 오류나 Valkey 조회 실패는 아니다.starting RTC session이 0건이며, 4건은 5분 뒤 empty timeout, 1건은 40초 뒤 Web의 DeleteRoom으로 닫혔다. 따라서 job 실패 자체의 수업 영향은 없다. 실제 영향은 그 앞의 아동 연결 끊김이고, 아동 앱의 새 join으로 회복됐다.로그 전체(162,986행, 1,120 job)에서 수업 진행에 직접 영향을 줄 수 있는 문제는 3종이며 모두 드물다. 반복적인 수업 장애 패턴은 없다.
| # | 증상 | 건수 | 영향 |
|---|---|---|---|
| 1 | job 시작 실패 model config metadata was not found | 5 | 해당 dispatch에서 AI 미기동. 4건은 같은 room 새 job으로 회복 |
| 2 | Typecast TTS 502 Bad Gateway | 9 | 발화 1회 누락. 외부 공급자 오류, 15:06~21:14 산발 |
| 3 | OpenAI Realtime server_error | 2 | 응답 1회 실패 (17:36, 19:18) |
3. 입출력 흐름 — job 시작 실패의 인과
Web /api/livekit/call → 토큰 발급: 참가자 metadata = configRef, RoomAgentDispatch.metadata = configRef (같은 값) → 아동 join → room 생성 → job 시작 → 정상 수업 → 아동 PC 연결 끊김 (participant closing: PEER_CONNECTION_DISCONNECTED) → 20초 뒤 LiveKit이 room 종료 (closing idle room: departure timeout) → 아동 클라이언트가 늦게 resume 시도 (room 종료 1초~9.5분 뒤) → LiveKit: 같은 이름으로 새 room 생성 (selected node for room) + 토큰 roomConfig의 RoomAgentDispatch → assigned job to worker + 아동 join 거부 (could not handle new participant: could not restart participant) → job: list_participants = 0명 → RuntimeError → unhandled exception → 빈 room은 5분 뒤 empty timeout으로 종료 (#5만 40초 뒤 Web DeleteRoom) → 아동 앱이 새로 join → 새 room·새 job → 회복
LiveKit 서버 로그 대조 (Loki service_name="ppi-livekit")
| # | 이전 room 종료 | resume 실패 + job 배정 | 간격 | 빈 room 종료 |
|---|---|---|---|---|
| 1 | 18:03:21 | 18:03:22 | 1초 | 18:08:22 empty timeout |
| 2 | 18:37:01 | 18:37:12 | 11초 | 18:42:12 empty timeout |
| 3 | 19:27:51 | 19:31:35 | 약 4분 | 19:36:35 empty timeout |
| 4 | 19:50:02 | 19:50:03 | 1초 | 19:55:03 empty timeout |
| 5 | 19:59:54 | 20:09:23 | 약 9.5분 | 20:10:03 API_DELETE |
같은 시간대 could not restart participant는 6건이다. 6번째(18:18:08, 0af1c571)는 이전 room이 닫히기 2초 전에 들어와 새 room이 생기지 않았고 job도 없었다.
배제 근거
- configRef 형식 오류: 이 경우
ignoring invalid LiveKit configRef participant metadata경고가 남고 RuntimeError가from metadata_error로 연결된다. 로그 전체 0건, traceback에 연결 원인 없음. - Valkey 스냅샷 없음·조회 실패:
fetch_model_config_snapshot_from_valkey의 예외가 그대로 올라오며 이 RuntimeError까지 도달하지 않는다.
4. 세부 — 실패 job과 회복
| 실패 KST | room (앞 8자) · 활동 | 실패 job | 같은 room 다음 job |
|---|---|---|---|
| 18:03:22 | 9b548454 · lesson-23 tiki_basic | AJ_NSdRH6Vk9N3D | 18:03:57 (+35초) |
| 18:37:12 | 80fa9fdf · lesson-9 newpp08 | AJ_M3butGDbpmyX | 18:38:11 (+1분) |
| 19:31:35 | 353524ae · lesson-10 newpp10 | AJ_MEozpcPcrbpx | 19:31:56 (+21초) |
| 19:50:03 | 125c6e7c · lesson-13 newpp11 | AJ_m9efznRB5B6j | 19:54:57 (+5분) |
| 20:09:23 | c03875fb · lesson-20 tiki_basic | AJ_sm8xWMbGHBrq | 없음 — 40초 뒤 Web이 room을 DeleteRoom (세션 정리 경로) |
로그가 WARNING 이상만 담고 있으나, 거의 모든 job이 시작 시 turn_detection is deprecated 경고를 남기므로 "다음 job 없음"은 의미 있는 신호로 본다.
무해로 분류한 경고
| 메시지 | 규모 | 판단 |
|---|---|---|
livekit-nc noise cancellation not authorized / unavailable | ≈100k행 | LiveKit Cloud 전용 기능. self-hosted에서 상시 발생 |
event loop blocked — ai_coustics/_ffi.py | job당 1~2회 | p50 213ms, p99 255ms, 최대 541ms. 세션 초기화 시점. 1초 이상 차단 0건 |
VAD inference is slower than realtime | 37 job | job당 1~4회, 최대 1.0초. 9/15 좀비 job 같은 연속 누적 없음 |
skipping reply … cannot be interrupted | job당 ≤17 | AI 발화 중 아동 발화. 정상 동작 |
voice_lifecycle_publish_failed / PublishDataError | 세션당 2건 | 세션 종료 시점 room close 후 발행 |
| turn_detection deprecated · drop unknown FFI handle · ASR continuation RPC unsupported | 매 job | 상시 경고 |
같은 메시지가 두 가지 JSON 형식으로 중복 기록되어 실제 건수는 원시 행 수의 약 1/3이다.
5. 적용한 수정과 주의사항
ModelConfigParticipantMissingError로 분리하고, entrypoint가 unhandled exception 대신 WARN 로그(model config participant missing; shutting down job, jobId·participantCount)를 남긴 뒤 request_shutdown("model_config_participant_missing")으로 정상 종료한다. ctx.connect() 전에 종료하므로 빈 room에 AI가 들어가지 않는다.
try:
config, config_snapshot = await _fetch_model_config(ctx.room.name)
except ModelConfigParticipantMissingError as exc:
logger.warning("model config participant missing; shutting down job", ...)
request_shutdown("model_config_participant_missing")
return
- configRef 형식 오류(
from metadata_error)와 Valkey 오류는 계약·인프라 문제라 지금처럼 예외로 남긴다. - SDK(livekit-agents 1.x)는 connect 전
ctx.shutdown()을 정상 종료 경로로 처리한다(_ctx_shutdown_called). - 테스트:
apps/livekit-agent/tests/test_model_config_participant_missing.py5건 추가, 전체 529 passed.
ctx.job.metadata 우선 사용은 적용하지 않았다. 원인이 "아무도 들어오지 않을 room"으로 확정됐기 때문에, 이를 적용하면 빈 room에서 AI 세션이 기동되어 job max duration(45분)까지 슬롯을 점유한다(9/15 좀비 job과 같은 위험).6. 인수인계용 요약
자료: ppi-livekit-agent-prod-20261027_1330-2130-warning-error.log (45MB, 162,986행) + Loki ppi-livekit 10/27 18:00~20:30 (43,139행). 수업 영향 후보: job 시작 실패 5건(RuntimeError LiveKit valkey model config metadata was not found, agent.py _fetch_model_config), Typecast 502 9건, OpenAI Realtime server_error 2건. job 실패 원인 확정: 아동 PEER_CONNECTION_DISCONNECTED → 20초 departure timeout으로 room 종료 → 늦은 resume이 같은 이름 room 재생성 + RoomAgentDispatch로 job 배정, join은 could not restart participant로 거부 → list_participants 0명. 5개 room 모두 참가자 0, 4건 empty timeout·1건 API_DELETE. job 실패 자체는 수업 영향 없음. 수정(로컬·미커밋): ModelConfigParticipantMissingError + ppi_agent에서 WARN 후 request_shutdown("model_config_participant_missing"), connect 전 종료. ctx.job.metadata 우선안은 빈 room AI 기동·슬롯 점유 위험으로 기각. 남은 축: 클라이언트 resume 실패 처리(별도 이슈).