Director

Appearance

Troubleshooting ​

Director never finishes loading ​

Symptom: the spinner sits there. The "Loading Director..." text never goes away.

<matrix-dsl-host> is not reaching data-status="connected". Check, in order:

  1. Browser console — any error from the bootstrap fetch (/api/v1/host/bootstrap or similar gateway path).
  2. curl -fsS <gateway>/healthz — gateway up?
  3. hivecast status — Host running?
  4. WebSocket upgrade — does wss://<gateway>/nats-ws open in DevTools → Network → WS?

If WebSocket connects but data-status remains "connecting", the bootstrap response is missing required fields. directorReadiness() requires host.getAttribute('root'), host.dataset.addressRoot, and host.dataset.runtimeTargetRoot (src/index.ts:81-114).

Tree empty after refresh ​

Topology label says "no live runtime attached". Check:

  1. matrix invoke system.runtimes runtimes.registered '{}' — are runtimes actually registered?
  2. matrix invoke system.registry registry.list '{}' — are claims present?
  3. <host-home>/runtimes/*.json — are the runtime records well-formed?

Tree loads but every actor shows "compat" badge ​

Deployment is mounting legacy aliases. Canonical roots are missing. Verify:

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

If that fails but matrix invoke system.memory $introspect '{}' succeeds, the agents package is shipping the legacy mount only. Update to a build that exposes system.agents.memory.

Memory tab returns nothing ​

DirectorDataAdapter.searchMemory walks ['system.agents.memory', 'system.memory']. If both fail, the tab gets an empty list. Confirm:

bash
matrix invoke system.agents.memory memory.search '{"mount":"system.agents","query":"test","limit":5}'

Sessions tab shows backend "legacy" ​

Same compat issue, but for system.agents. The $sessionList candidate list is currently ['system.agents'] only — the legacy bracket has been collapsed. If "legacy" appears, it is informational; the canonical mount responded.

Chat tab shows "unavailable" ​

DirectorChatSurfaceHost failed to load @open-matrix/chat-component/surface:

  1. Was Director rebuilt after a chat-component change? Stale Director dist sometimes references a chunk hash that no longer exists.
  2. Look in the Network tab for the failed request — typically a 404 on /apps/director/assets/<hash>.js.
  3. Force a hard reload (Ctrl/Cmd+Shift+R) — service-worker / browser cache can hold stale chunk-manifest entries.
  4. As a last resort, clear <host-home>/runtimes/RUNTIME-...-DIRECTOR.json's cache and restart the runtime.

The "unavailable" message is rendered by renderUnavailable() (DirectorChatSurfaceHost.ts:163-174) and includes the rebuild hint inline.

Ops Feed empty even though actors are emitting ​

DirectorRuntimeAdapter.queryOpsFeed requires system.observability.tracing (or system.tracing) to be reachable. Confirm:

bash
matrix invoke system.observability.tracing $introspect '{}'
matrix invoke system.observability.tracing trace.query '{"limit":5}'

If the introspect succeeds but the query returns nothing, the tracing actor isn't recording (provider misconfigured, or sample rate is zero).

"Mount is not registered in system.registry: …" ​

Thrown by DirectorRuntimeAdapter.resolveCanonicalTarget (src/services/DirectorRuntimeAdapter.ts:185-198). The canonical mount the user clicked has no binding rule. Possible causes:

  • Race: the registry hasn't received the runtime's claims yet. Refresh.
  • The runtime is up but its claim was rejected. Check the runtime log.
  • The user clicked a synthetic prefix node (e.g., system.observability itself, with no actor mounted). That's expected; the adapter is not asked to introspect prefix nodes.

Top-bar shows "browser session unknown" ​

DirectorTopology.resolveDirectorTopology could not normalize a browser root. The bootstrap did not populate data-address-root. Usually means the user is not signed in or the gateway didn't authenticate them.

See also ​

Source: projects/matrix-3/packages/director/src/services/DirectorRuntimeAdapter.ts:185-198 (resolution error), DirectorTopology.ts (label logic), DirectorChatSurfaceHost.ts:84-115 (chat failure modes).