Shutdown handler not invoked when call is not received or is disconnected

[sagorbrur]

Bug Description

When a call is not received or is disconnected prematurely, the shutdown process does not appear to execute as expected. In these scenarios, the shutdown handler is never entered, and the process is eventually forcefully terminated.

As a result, the following errors are logged:

2025-12-25T14:15:32.567988716Z stdout F {"message": "process did not exit in time, killing process", "level": "ERROR", "name": "livekit.agents", "pid": 68, "job_id": "AJ_iMXGj8t3AVnY", "room_id": "RM_dUSn3teUhuCS", "timestamp": "2025-12-25T14:15:32.567808+00:00"}

2025-12-25T14:15:32.568078676Z stdout F {"message": "killing process", "level": "INFO", "name": "livekit.agents", "pid": 68, "job_id": "AJ_iMXGj8t3AVnY", "room_id": "RM_dUSn3teUhuCS", "timestamp": "2025-12-25T14:15:32.568001+00:00"}

Observed behavior

• The shutdown method is not invoked when the call is unanswered or terminated unexpectedly.
• The process exceeds the allowed shutdown time and is forcibly killed.

Question
What could be the underlying reason the shutdown handler is not being triggered in this scenario? Are there known conditions under which the shutdown callback may be skipped when a call is not successfully established?

Expected Behavior

When a call is not received or is terminated before being fully established, the application should:

• Gracefully invoke the shutdown handler.
• Release all resources associated with the call (e.g., connections, workers, or background tasks).
• Exit the process cleanly within the configured shutdown timeout.
• Avoid forceful process termination and related error logs.

Reproduction Steps

1. Start the agent/service and initiate an outbound call to a user.
2. Do one of the following:

   * Allow the call to ring without being answered, **or**
   * Disconnect it immediately.
3. Observe the application lifecycle after the call is not received or is terminated.
4. Wait for the configured shutdown timeout to elapse.
5. Review the application logs.

Operating System

ubuntu 22.04

Models Used

Deepgram, OpenAI, ElevenLab

Package Versions

livekit-agents=1.3.10

Session/Room/Call IDs

roomID: RM_dUSn3teUhuCS

Proposed Solution

Additional Context

No response

Screenshots and Recordings

No response

[sagorbrur]

similar to 4152

[longcw]

can you share a reproducible example, like do you have generate_reply called after session started or in on_enter, is the allow_interruptions set to False?

[sagorbrur]

Hi @longcw ,
Yes, generate_reply is called in on_enter (after session started) with allow_interruptions=False.

await self.session.generate_reply(
    instructions=welcome_prompt, 
    allow_interruptions=False
)

We have followings method integrated:

1. generate_reply is called inside on_enter (which runs after the session has started)
2. allow_interruptions=False is explicitly set
3. Audio input is disabled before the call (self._safe_set_audio_enabled(False)) and re-enabled after
4. There's a configurable delay (welcome_message_delay_in_seconds, default 2.0s) before calling generate_reply

[longcw]

I cannot reproduce the issue with the basci_agent example. the isssue related to generate_reply and allow_interruptions=False should be fixed in #4346 and #4211 and mentioned in #4152. can you share a minimal reproducible example?

or can you verify if the issue fixed if you remove the generate_reply or enable allow_interruptions?

[sagorbrur]

Hi @longcw ,
Thank you. I will try the below part you have suggest. Will get back to you soon.

[sagorbrur]

Hi @longcw, thanks for the response.

I tried removing the generate_reply call, and also tested with allow_interruptions=True, but unfortunately, the issue still persists. The shutdown handler is still not being invoked for unanswered outbound calls.

Our Setup

Here's how we handle the shutdown callback registration:

1. Shutdown callback is registered AFTER session.start():

# Session starts here
await session.start(agent=our_agent, room=ctx.room, room_input_options=RoomInputOptions(
    noise_cancellation=noise_cancellation_plugin,
))

# ... some other setup code ...

# Shutdown callback is registered later
shutdown_callback = await create_shutdown_callback(
    our_emitter=vb_event_emitter,
    request_reply_handler=request_reply_handler,
    our_api_client=our_api_client,
    call_id=call_id,
    # ... other params
)

ctx.add_shutdown_callback(shutdown_callback)

2. For outbound calls, we wait for participant in on_enter():

async def on_enter(self):
    is_outbound_call = self.room_name.startswith("obd.phonecall")

    # For outbound calls, wait for participant to connect first
    if is_outbound_call:
        await self._participant_connected.wait()
        logger.info("Participant connected, proceeding with on_enter delay")

3. Our shutdown handler has a fast path for unanswered calls:

async def execute_shutdown(self, reason: str):
    logger.info(f"Shutting down.... Reason: {reason}")

    # Check if this is an unanswered call (NO_ANSWER or CALL_FAILED)
    is_unanswered_call = reason in [
        end_call_reasons_enums.NO_ANSWER,
        end_call_reasons_enums.CALL_FAILED,
    ]

    if is_unanswered_call:
        logger.info(f"Unanswered call detected, using fast shutdown path for call {self.call_id}")
        await self._execute_fast_shutdown(reason)
        return
    # ... normal shutdown for answered calls

[sagorbrur]

Hi @longcw ,
I also reverted to 1.2.18, and it's working fine. It might problem with 1.3.

[longcw]

I see now, I think the issue is you are waiting for the participant in the on_enter. when shutting down the agent session, it won't cancel the on_enter but just wait for it to done, await self._participant_connected.wait() will cause a deadlock during shutting down.

you can register the shutdown callback first, then wait for the participant before starting the agent session, for example

async def entrypoint(ctx: JobContext):
    usage_collector = metrics.UsageCollector()
    async def log_usage():
        summary = usage_collector.get_summary()
        logger.info(f"Usage: {summary}")

    # shutdown callbacks are triggered when the session is over
    ctx.add_shutdown_callback(log_usage)

    await ctx.connect()
    await utils.wait_for_participant(ctx.room)

    # AgentSession definition...

[sagorbrur]

Hi @longcw ,
Thank you. I will check and get back to you shortly.

[sagorbrur]

Hi @longcw ,
After following your suggestions, it's working now.
Thank you so much.