Attempt to save large beam teams results in UI getting stuck in beam mode and refusing to go back to chat

[Slava-256]

What's happening?

I am trying to create a beam team with 24 beams and 10 custom merges, each custom merge is about 80K of text.

After I save the team, I cannot exit the beam mode, either using Esc key or X button at the top of the UI.

I have to reload the page (Ctrl-R) to go back to chat.

If I have only 1 or 2 of the large custom merges, things are fine. The issue starts to appear at 3 merges.

If I open up Logs Viewer in Application->Preferences->Tools, I see:

8 minutes ago | error | unhandled | Uncaught error

{
"message": "The quota has been exceeded.",
"stack": "setItem@https://app.big-agi.com/_next/static/chunks/pages/",
"filename": "https://app.big-agi.com/_next/static/chunks/pages/",
"lineno": 132,
"colno": 9106
}

Where does this happen?

Big-AGI Pro (big-agi.com)

Impact on your workflow

Medium - Workaround exists

Environment (if applicable)

No response

Additional context

No response

[github-actions]

Thanks for the detailed report and repro steps, @Slava-256.

Assessment

The root cause is a localStorage quota exceeded error (QuotaExceededError) that blocks state updates when closing Beam.

Why it happens

Big-AGI persists ~20 Zustand stores to localStorage, which has a browser-enforced quota of ~5-10 MB per origin. Only the chat/conversations store uses IndexedDB (higher quota); everything else - including the Beam module store (app-module-beam), the models store (app-models), UI preferences, and many others - all compete for the same localStorage budget.

With heavy use (many configured models, accumulated settings, multiple beam presets), the aggregate localStorage usage can approach the quota. Any _set() call on a persisted store triggers localStorage.setItem(...) via Zustand's persist middleware - and when that exceeds the quota, it throws.

Why it blocks Beam exit specifically

The exit flow is:

1. terminateKeepingSettings() sets isOpen: false on the vanilla Beam store (not persisted - this part works)
2. A Zustand subscription in ConversationHandler (src/common/chat-overlay/ConversationHandler.ts:45-48) fires synchronously and calls useModuleBeamStore.getState().setBeamOpenForConversation()
3. That _set() triggers persist middleware → localStorage.setItem('app-module-beam', ...) → throws QuotaExceededError
4. The uncaught error disrupts the subscription chain, preventing the UI from reflecting the closed state

The error shows as "Uncaught error" in the logs because Zustand's default createJSONStorage (localStorage wrapper) does not catch setItem failures - unlike the chat store which uses a custom createIDBPersistStorage() with explicit error handling (src/common/util/idbUtils.ts).

Why 3+ large custom merges is the threshold

While the custom merge instructions themselves live in the vanilla Beam store (not persisted to localStorage), having more active fusions increases the number of state updates and persist writes during a session. The real trigger is the cumulative localStorage size from all ~20 stores reaching the quota boundary - at which point any write (even a small one like updating openBeamConversationIds) tips it over.

Suggested fixes

1. Immediate resilience (recommended first step): Add a custom storage adapter for store-module-beam.tsx that wraps setItem in a try-catch, matching the pattern already used by the chat store:

// In store-module-beam.tsx, add a safe localStorage wrapper:
import { createJSONStorage } from 'zustand/middleware';

const safeLocalStorage = createJSONStorage(() => ({
  getItem: (name: string) => localStorage.getItem(name),
  setItem: (name: string, value: string) => {
    try {
      localStorage.setItem(name, value);
    } catch (error) {
      console.warn(`[beam] localStorage.setItem('${name}') failed:`, error);
    }
  },
  removeItem: (name: string) => localStorage.removeItem(name),
}));

// Then in the persist config:
persist((...) => ({...}), {
  name: 'app-module-beam',
  version: 1,
  storage: safeLocalStorage,  // <-- add this
  ...
})

This ensures Beam exit always works even when storage is full - the persist failure is logged but non-blocking.

2. Broader fix: Apply the same safe-storage pattern to all localStorage-backed stores, or create a shared createSafeLocalStorage() utility. This prevents the same class of bug from hitting any other store.

3. Longer term: Consider migrating larger/growing stores (like app-models) to IndexedDB, reducing localStorage pressure overall. The pattern is already established in idbUtils.ts.

Workaround (immediate relief)

If you hit this state, you can free up localStorage space in DevTools:

1. Open DevTools → Application → Local Storage → https://app.big-agi.com
2. Look for large keys (sort by value size if possible)
3. Delete any you can afford to lose (e.g. old app-module-* keys)
4. Reload the page

Alternatively, reducing the number of saved beam presets or clearing unused ones before saving new large teams should help stay under the quota.

[Slava-256]

Interestingly, when I added the same 80k merge instruction as a custom merge to my AI Persona, and then invoked the Persona's custom merge 10 times, I was able to save the resulting team!

[enricoros]

@Slava-256 Thanks for reporting. This is a critical issue I'll work on. The beam teams are saved to the "local storage" a 5MB storage space in the browser (for legacy reasons). When exceeded, writes fail, and the application can begin having issues.

For a proper fix, I need to transfer Beam Teams to the same storage as Personas and Chats (with infinite space up to hard drive capacity), including migration of the existing teams and freeing of the formerly used space.

Not an issue, just something I had to do sooner rather than later. I'll assign this the highest priority - it's a matter of data corruption.

In the meantime using Personas work because they benefit from unlimited storage.

[Slava-256]

@enricoros Thank you for looking into it.

I have a question. When I load a team that was previously saved with 10 persona based merges, it looks indistinguishable from a team with 10 custom merges. I see edit boxes for merge system instruction and user message.

So my initial impression was that persona merges are getting converted into custom merges upon save.

Could you clarify how does it actually work?

Because if the persona merges are converted into custom merges upon save, then it is unclear why it does not cause an error that looks like it is triggered by the total size of custom merge instructions.

But if persona merges are saved by reference, what would happen if such a team is loaded after a given person has been deleted?

[enricoros]

Exactly, they are saved by reference. When editing the Persona merges there's a button to save it back to the personas. So 10 merges = 10 references in that case.

[enricoros]

Update: added a public developer tool to fully inspect the localStorage, to debug issues when running out of space. It's in the /dev/inspect/storage folder of the big-agi installation, such as https://app.big-agi.com/dev/inspect/storage