Chat

Appearance

Troubleshooting ​

Chat page never loads ​

Symptom: the page stays at the loading spinner.

Check:

  1. Browser DevTools → Network. Did index.html load? Did the bundled JS load? Any 404s on assets/*.js?
  2. WebSocket connection to /nats-ws — is the WS handshake completing?
  3. <matrix-dsl-host> data-status attribute — what value? connecting means WS open, bootstrap not done.
  4. hivecast status and hivecast runtimes — Host alive, CHAT runtime running?

If data-status === 'connected' but the page still shows the loading screen, the readiness logic is waiting on Chat-side initialization. Open the browser console for [MatrixChat] errors.

"No bound runtime config and no explicit runtime-mode declaration were found" ​

Source: bind-chat-services.ts:111. Means: the page was rendered but bindChatServices was never called with a config. Two ways this happens:

  • Wrong bootstrap path. The Host Service runner didn't call createHostManagedChat before mounting the page. Check the runtime's startup code.
  • Wrong runtime-mode hint. In dev mode, chat-app[runtime-mode] or matrix-dsl-host[bootstrap-mode] must declare the mode. Without either, the resolver throws.

Fix: ensure the runtime entrypoint binds services before the browser tries to read them.

"[Dependency Unavailable: No activity completed on the prompt stream...]" ​

Source: ChatApp.ts:3296. Means: Chat sent a prompt to system.agents, no $activity frames returned within the timeout, and the dependency probe found a missing service.

Check, in order:

  1. matrix invoke system.agents $ping '{}' — agent responds?
  2. matrix invoke system.inference status.get '{}' — effective.provider set?
  3. Provider credentials in system.factotum?
  4. Provider driver runtime running? (matrix invoke system.runtimes runtimes.registered '{}' should include the driver app.)

See inference dependency.

"Prompt rejected by system.agents for <target>" ​

system.agents ACK returned ok: false. Read the ACK content — it usually includes a reason. Common causes:

  • Target mount is not registered in system.registry.
  • principalId is missing and system.agents requires it.
  • Session ID was specified but does not exist.

Sessions tab shows backend "legacy" ​

The Sessions tab in Director surfaces the backend mode. If it shows legacy, Chat (or Director) fell back from the canonical mount to the compat alias. Run:

bash
matrix invoke system.agents $introspect '{}'
matrix invoke system.agents.memory $introspect '{}'

If the agents introspect succeeds but the memory introspect fails, the deployment mounts only the legacy alias for memory. Update the agents package to a build that exposes system.agents.memory.

Stream timeout ​

Source: ChatApp.ts:3295 (stream timeout — no events received). Means: streaming started, and then $activity frames stopped arriving. Check:

  • system.observability.tracing is mounted; trace activity for the chat session.
  • journalctl -u matrix-host-edge.service for provider-driver errors.
  • Per-runtime log for the inference driver.

Inline component fails to mount ​

User typed /files and nothing appeared. Likely causes:

  • The mx-files component is not registered (its package is not running).
  • chat.messages rejected the messages.add-component op.

Verify the package is up:

bash
matrix invoke system.runtimes runtimes.registered '{}' | jq '.runtimes[] | .app'

Persisted session won't resume ​

User picks an old session, transcript stays empty. Check:

bash
matrix invoke system.agents session_state.read \
  '{"sessionId":"<id>","key":"transcript"}'

If data is empty/null, the session existed but had no persisted transcript (e.g., it was abandoned mid-prompt before any frame completed). Start a new session.

Theme didn't change after /theme ​

config.theme.persistScope: 'user' requires ChatPreferencesProxy to be reachable. If the proxy is offline, the theme change is local-only and won't persist past reload. Check chat.preferences is mounted.

See also ​

Source: projects/matrix-3/packages/chat/src/ChatApp.ts:3287-3401 (timeouts/dependencies), chat/src/runtime/bind-chat-services.ts:108-115 (mode error), chat/src/contracts/IChatConversationService.ts (rejection shape).