FlowPad

Appearance

Troubleshooting ​

This page enumerates failure modes that have actually appeared in development, what to look for, and the verified fix. If a symptom is not listed here, the next places to look are the transport log, DevTools Network panel, and <host-home>/logs/runtimes/FLOWPAD.log.

Actor tree is empty ​

Symptom. The sidebar's actor tree shows "No actors discovered yet." even though the Host has runtimes.

Likely causes.

  1. The page loaded before the gateway finished announcing the runtimes. The actor-tree refresh button is a manual re-discover; click it.
  2. data-authority-root is missing from the host element, so the catalog target defaults to FLOWPAD-AUTHORITY/system.catalog, which doesn't exist on this Host. Check DevTools elements panel for <matrix-dsl-host>'s data attributes.
  3. Federation failure — the $catalog mount is unreachable. The transport indicator goes red and the actor-tree status shows "Failed to load catalog".

Fix.

  • Pass an explicit catalog target via URL: ?catalog=COM.NIMBLETEC.RICHARD-SANTOMAURO/system.catalog.
  • Verify system.catalog is mounted: matrix invoke system.catalog $introspect '{}' --home /tmp/matrix-home.
  • Check the Host's gateway has the right authority root: hivecast status --home /tmp/matrix-home | jq .authorityRoot.

Run button produces nothing ​

Symptom. Click ▶ RUN; nothing happens, no flowStarted in transport log, no error.

Likely causes.

  1. The editor is empty (the run button still emits requestRun, but FlowpadApp has nothing to compile).
  2. The actor's mount path is unreachable — the page's _context is stale because the WebSocket reconnected mid-run.
  3. The shell's _domWired flag is false because _onContextUpdated hasn't fired (race condition with custom-element registration order).

Fix.

  • Type at least one character. The shell only fires on Ctrl+Enter or run button if code is non-empty.
  • Reload the page. If the actor tree was empty before, the Run flow won't have an authority root either.
  • Check console: any [PipelineEditor] warnings during boot.

Federation timeout (cross-root calls fail) ​

Symptom. A flow targeting $CATALOG_TARGET or any address with a / in the mount returns flowError: timeout after 30000ms.

Likely causes.

  1. Backbone broker URL is empty or wrong. The default backbone is '' (empty); cross-root calls go through whatever transport the browser established.
  2. The remote authority root isn't routable from this Host. Federation is opt-in; not every Host has a leaf connection.

Fix.

  • Check the transport indicator. If it says "Transport: Local (InMemory)" you're not federated; cross-root won't work.
  • Restart the runtime in hivecast mode: matrix up @open-matrix/flowpad --serve --env hivecast (vs --env dev).
  • For a local-only test, change the example to use the local db mount: ./db instead of $CATALOG_TARGET.

Stale dist/ (changes don't appear after rebuild) ​

Symptom. You changed source code, ran pnpm --filter @open-matrix/flowpad build, reloaded the page — but the changes don't appear.

Likely causes. Per project rule "REBUILD BEFORE TESTING" in CLAUDE.md / MEMORY.md: tests use BUILT artifacts, stale bundles = false results. The gateway is serving from a different dist/ than the one you rebuilt.

Fix.

bash
# Confirm dist mtime matches your latest build
ls -la projects/matrix-3/packages/flowpad/dist/index.html

# If you're running from a hivecast release (e.g. /home/ubuntu/hivecast/releases/...),
# rsync the new dist over.

# Then hard-reload the browser (Cmd/Ctrl+Shift+R) — Vite hashes assets, so stale files
# can be cached aggressively.

For two-runtime topology, both matrix-web and matrix-edge need the rebuilt FlowPad bundle since each --serve runtime mounts its own copy.

Transport indicator red / "Connection lost" ​

Symptom. The header transport indicator displays a red dot or "Transport: disconnected".

Likely causes.

  • The browser's WebSocket to /nats-ws was rejected (auth?), dropped (server restart?), or never opened (404 — gateway not running).

Fix.

bash
# Verify the gateway is alive
curl -fsS http://127.0.0.1:3100/healthz | jq .

# Verify /nats-ws exists
curl -I http://127.0.0.1:3100/nats-ws
# Expect: 101 Switching Protocols (websocket upgrade)

If the WebSocket is fine but FlowPad still says disconnected, it's a transport-indicator bug — file an issue with the console output.

"Project manifest contract failed" on load ​

Symptom. Console shows Project manifest contract failed: ... and the package browser is empty.

Likely cause. A src/projects/<id>/manifest.json references an unknown component alias, references a missing project id, or a split view is missing both templateFile and styleFile. Validation logic is in projectCatalog.ts:359-396.

Fix. Read the error message — it names the offending project id and the field. Edit the manifest, rebuild, reload.

Five-representation parity errors ​

Symptom. A 'Serialize: HTML'-class flow returns "could not parse component schema".

Likely cause. The input value is not a component schema — compileSourceToCanonicalIR fell through to the default flow-dsl branch and produced a query plan instead of a schema IR.

Fix. Pass sourceFormatHint: 'serialization-html' to runFromCode, or wrap the call in flow().fromValue({ ... }).viaRemote("./...", "$introspect") first to get a schema you then convert.

When in doubt ​

bash
# Full health snapshot
hivecast status --home /tmp/matrix-home | jq .
hivecast runtimes --home /tmp/matrix-home

# Re-seed and retry
hivecast doctor --home /tmp/matrix-home --repair

See also ​

Source: projects/matrix-3/packages/flowpad/src/FlowpadApp.ts:336-371 (timeout policy), projects/matrix-3/packages/flowpad/src/shell/projectCatalog.ts:355-395 (manifest validation).