OpenHands / OpenHands/software-agent-sdk

[Bug]: Agent Server event endpoints hang indefinitely when LocalConversation cleanup blocks

Open
#4,555 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug priority:medium sdk
Dominant language
Python
Stars
1.1k
Forks
539
Avg merge
1d 19h
Merged PRs (30d)
137

Description

Is there an existing issue for the same bug?
  • I have searched existing issues and this is not a duplicate.
Bug Description

In Agent Server v1.42.1, event endpoints for an existing conversation can hang
indefinitely after LocalConversation cleanup becomes stuck.

The conversation UI then remains in a loading state. Restarting the Agent Server
temporarily restores access, but the issue can recur.

Expected Behavior

Conversation cleanup must be bounded and must not indefinitely block event
retrieval. If cleanup fails or exceeds a timeout, the server should log the
failure and continue serving event endpoints.

Actual Behavior

The following endpoints time out for an existing finished conversation,
including when requesting only one event:

  • GET /api/conversations/{id}/events/count
  • GET /api/conversations/{id}/events/search?limit=1
  • GET /api/conversations/{id}/events/search?limit=50

At the same time, GET /server_info and GET /api/conversations/{id} return
successfully. This suggests the problem is not a general Agent Server outage or
a large event-history scan.

Steps to Reproduce
  1. Start openhands-agent-server with LocalConversation storage.
  2. Create and finish one or more conversations.
  3. Open or reload an existing conversation in the UI.
  4. Request either /events/count or /events/search?limit=1 for that
    conversation with a valid session key.
  5. Observe that the request does not return and the conversation remains loading.

The issue is intermittent and appears when LocalConversation cleanup blocks
during portal shutdown; it may require multiple conversations or reloads to
trigger.

Acceptance Criteria
  • A stalled conversation cleanup cannot block event endpoints indefinitely.
  • /events/count and /events/search?limit=1 return or fail with a bounded timeout.
  • The server logs enough context to identify a cleanup timeout.
  • Existing conversations remain loadable after another conversation's cleanup stalls.
Installation Method

Docker image deployment

If you selected "Other", please specify

No response

SDK Version

1.42.1

Version Confirmation
  • I have confirmed this bug exists on the LATEST version of OpenHands SDK
Python Version

3.13.13

Model Name (if applicable)

Not applicable; the issue occurs while reading stored conversation events.

Operating System

Linux

Logs and Error Messages

py-spy captured a worker blocked in the conversation cleanup path:

threading.join
anyio.from_thread.start_blocking_portal.exit
openhands.sdk.utils.async_executor.close
openhands.sdk.conversation.impl.local_conversation.close

Minimal Code Sample

No response

Screenshots and Additional Context

A downstream mitigation with a bounded timeout around portal and conversation
cleanup prevents the UI from remaining permanently loading. The underlying
cleanup operation can continue in the background, but it no longer blocks event
serving.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the cleanup path through LocalConversation.close, openhands.sdk.utils.async_executor.close, and any anyio.from_thread.start_blocking_portal shutdown handling shown in the py-spy stack. Reproduce the stall with /events/count and /events/search?limit=1 while another conversation cleanup is blocked. Done means cleanup cannot indefinitely block event retrieval, timeouts are logged with useful context, and existing conversations remain loadable.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.