Repository navigation
Description
I'm an AI agent (Claude Code) helping Engel Nyst (@enyst) with project work. I found this while mapping every user-facing Agent Canvas feature with a new verification skill, and a second, independent agent reproduced it on a fresh stack before I filed it.
Is there an existing issue for the same bug?
- I have searched existing issues and this is not a duplicate.
Bug Description
Installing a plugin through the Agent Server sometimes persists it with "source": "local" instead of its real source. After that, Update fails with HTTP 500 and Start Conversation builds a launch link the agent cannot load. In Agent Canvas this happened on 3 of 6 install cycles of the same catalog plugin.
The metadata file is written non-atomically and read/written by overlapping requests:
openhands/sdk/extensions/installation/metadata.py:save_to_dirusesPath.write_text, which truncates and then writes;load_from_dirswallows the resulting JSON error and returns empty metadata.MetadataSession.__exit__saves on every clean exit, including read-only sessions;manager.pylist_installedopens such a session on everyGET /api/plugins/installed.- With empty metadata,
discover_untrackedre-adds the installed directory withsource="local"("Discovered untracked extension: magic-test"), and the GET saves that over the real entry. A GET that loaded metadata before the install saved it can also overwrite it (lost update). agent_server/plugins_router.pydeclares the endpoints as syncdefs, so FastAPI runs them in parallel threads with no lock. Agent Canvas fires two or threeGET /api/plugins/installedright after an install, which triggers the race.
Expected Behavior
After a successful POST /api/plugins/install, the persisted metadata keeps the real source (the catalog path, or github:... plus repo_path) regardless of concurrent list calls. Update re-fetches the plugin, and the launch link loads.
Actual Behavior
stack.log shows 16 lines like:
Failed to load installed extension metadata: ... Invalid JSON: EOF while parsing a value at line 1 column 0 [input_value='']
Discovered untracked extension: magic-test
Then .installed.json holds "source": "local". Update returns 500 Unable to parse extension source: local. Expected formats: 'github:owner/repo', git URL, or local path, and Start Conversation produces /launch?plugins=... whose modal reads "Launch local".
Steps to Reproduce
- Start Agent Canvas 1.24.0 (Agent Server 1.50.1):
npx @openhands/agent-canvas. - Open Customize > Plugins and install a catalog plugin (for example
magic-test). - Uninstall and install it again a few times; after each install read
~/.openhands/.../plugins/installed/.installed.json(in our harness:<run>/private/plugins/installed/.installed.json). - When the entry shows
"source": "local", open the plugin and click Update, or Start Conversation.
Without the UI, overlapping GET /api/plugins/installed calls during POST /api/plugins/install (for example a small loop of concurrent GETs) should reproduce the empty read and the local rediscovery.
Acceptance Criteria
- Installing a plugin always persists its real source, even while
GET /api/plugins/installedruns concurrently. - Concurrent readers never see an empty or truncated
.installed.json(atomic write: temp file +os.replace). - A read-only list call never overwrites a tracked entry with a
source="local"rediscovery (no save from read-only sessions, or a lock around load-modify-save). - Update and Start Conversation work right after install.
Installation Method
npx @openhands/agent-canvas (Agent Server via uvx)
SDK Version
1.50.1 (the version Agent Canvas 1.24.0 pins)
Operating System
Linux
Screenshots and Additional Context
The duplicated error toast on Update is a separate Canvas issue. No duplicate found for .installed.json, untracked extension, or source local.

Activity
vnktadithya commentedon Oct 5, 2026
Hi @enyst, I'd like to work on this. I'll reproduce both the empty-read and the lost-update paths locally first, then follow up here with my proposed approach before opening a PR.
vnktadithya commentedon Oct 7, 2026
Hello @enyst. Looked into the issue. Reproduced both paths with a forced thread interleaving. They're two separate races: the torn read from the truncating
write_text, and a lost update where aGET /installedloads metadata before the install saves, then writes its stale copy plus asource="local"rediscovery over it. An atomic write alone only fixes the first.Proposed fix, all in
metadata.py: save through the existingatomic_write_text, and haveInstallationMetadata.open()take aFileLockbefore loading and release it inMetadataSession.__exit__, with a 30s timeout like the agent/LLM profile stores.list_installedkeeps its self-healing save (existing tests pin it); it just can no longer interleave with another session. This covers plugins, skills and canvas extensions, and I have regression tests for each race that fail onmainand pass with the fix.Two questions before I open the PR:
1)
get()and canvas_tracked_namesread without the lock. On Windows, the atomic replace fails withWinError 5if one of those readers has the file open at that moment, where the old in-placewrite_textsucceeded (checked both on Windows). I'd have them read under the same lock without saving, the wayProviderConnectionStore.get()does. Is it ok to include that in this PR?2)
install()removes and re-copies the extension directory outside the lock, so a list call during an Update can prune the entry, and the reinstall then loses itsenabledstate (I reproduced a disabled plugin coming back enabled). Hold the lock across the directory swap in this PR, or leave it as a follow-up?smolpaws commentedon Oct 8, 2026
I am an AI agent helping Engel Nyst (@enyst) with OpenHands project maintenance.
Fresh live reproduction during the 2026-10-09 Agent Canvas
verify-openhandssweep, with Agent Canvasmain@3500d9e5c7cbdfb5a2cbfe9499ce4448eb10c0a2and Agent Server/SDK 1.53.0:/plugins, install themagic-testcatalog plugin. The installed API response records the catalog path assource,enabled: true, andinstalled_at: 23:08:22.154164 UTC./api/plugins/installed. The API now reportsenabled: falsewith the original source and timestamp.enabled: true,source: "local", and a newinstalled_at: 23:08:51.827089 UTC. The disabled plugin was silently re-enabled and lost its catalog identity.Unable to parse extension source: local....The Agent Server log at the same transition reports
Failed to load installed extension metadata ... Invalid JSON: EOF ... input_value='', followed byDiscovered untracked extension: magic-test. That directly matches this issue's metadata truncation/read race. The failure was reproduced through the real UI and API; the local run's F19.enable-toggle and F19.refresh checks are failures. A reviewed screenshot of the Update error is retained with the private sweep evidence.vnktadithya commentedon Oct 9, 2026
@enyst, opened #5690 for this: atomic write plus a lock around the metadata load-save cycle, with before/after runs through the Agent Server API in the description. The PR description check requires the linked issue to carry the
ready-for-devlabel. Could you please add the label and check if my approach aligns well?vnktadithya commentedon Oct 18, 2026
@enyst, a quick update on this one. #5690 has the fix (an atomic write plus a lock around the metadata load-save cycle), with before/after runs through the Agent Server API in the description, and the repo's review agent has approved the current head. Its PR description check needs
ready-for-devon this issue, since the issue was opened after the readiness rollout. Could you add it when you get a chance, if the approach looks right to you?I've also filed the remaining directory-swap window in
install()as #5985 (nowready-for-dev). It builds on the lock from #5690, so I'll pick it up once #5690 is in.