Chat Session Locks
Vulcan uses short-lived locks to prevent multiple simultaneous AI sessions from editing the same project at the same time. In most cases you'll never notice them — but if something goes wrong, this page explains what's happening and how to recover.
How locks work
When you send a message, Vulcan acquires a project-scoped lock before the AI starts working. The lock is held for 60 seconds and renewed every 30 seconds as the session progresses. When the AI finishes its turn, the lock is released.
This prevents two chat sessions from writing conflicting changes to the same project simultaneously — which would corrupt the code or produce unpredictable builds.
Locks are invisible when everything works normally. They acquire, renew, and release automatically. You only see them when something goes wrong.
Common lock errors
"A chat session is already in progress"
What it means: The project is locked by an active session. This is expected if you have the same project open in another tab or window and a response is in progress there.
What to do:
- Wait for the active session to finish, then try again
- If nothing is actively running, wait 60–120 seconds for the lock to expire on its own (see Stuck lock below)
"Maximum concurrent sessions reached"
What it means: You have 3 chat sessions actively running across all your projects simultaneously. Vulcan allows a maximum of 3.
What to do: Wait for one of your other sessions to finish, then try again. If you're not sure which sessions are running, check your other open tabs.
A project is stuck — every message returns "already in progress"
Symptoms: Sending any message immediately returns an error, nothing is running in the preview, and the problem persists after refreshing the page.
What happened: The AI's background workflow crashed before it could release the lock. The lock has a TTL and will eventually expire — but in rare cases this takes longer than expected.
If you can wait: Give it 60–120 seconds and try again. Locks always expire.
If you need it cleared now: Contact a platform admin and ask them to clear the lock at Admin → Locks (/admin/locks). They can:
- View all active locks in a table
- Clear a specific project's lock in one click
- Use the "Manual Clear" section if they have your project ID
Clearing a lock removes both the project lock and any per-user session slots. It does not affect your chat history, project files, or deployed app.
For platform admins
The Locks admin page
Go to /admin/locks in the Vulcan admin area.
Active Locks table — shows every project currently holding a lock, who holds it, and when it was acquired. Click Clear to release a specific project's lock immediately.
Manual Clear — if you have a project ID (visible in the URL when viewing a project), paste it in here and click Clear. Useful when you know which project is stuck but can't find it in the table.
What clearing does
- Removes the
shared:{projectId}:chat-lockkey from KV - Removes all
u:{userId}:chat-lock:{projectId}per-user session keys for that project - Does not affect project data, file storage, or chat history
When to clear vs wait
Clear immediately if:
- A user reports being stuck and needs to keep working
- The lock has been held for more than 5 minutes with no active response
Let it expire if:
- A session genuinely seems to be in progress (a deploy is running, logs are appearing)
- The user hasn't reported an issue — a lock clearing mid-session will interrupt the AI
Questions
Reach out in #eng_product_platform_team for help with stuck locks or repeated lock issues.