OpenHands / OpenHands/software-agent-sdk
[Bug]: Agent Server event endpoints hang indefinitely when LocalConversation cleanup blocks
Nobody has claimed this yet.
- 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
- Start
openhands-agent-serverwith LocalConversation storage. - Create and finish one or more conversations.
- Open or reload an existing conversation in the UI.
- Request either
/events/countor/events/search?limit=1for that
conversation with a valid session key. - 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/countand/events/search?limit=1return 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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