DF8106: Connection Meta Not Served

Message

The host cannot serve the RPC connection meta for devframe "{name}" (id "{id}") at "{base}" — its DevframeHost does not implement mountConnectionMeta.

Cause

A mounted devframe's SPA loads in an iframe at its own base (e.g. /__terminals/) and calls connectDevframe(), which fetches ./__connection.json relative to that base to discover the RPC/WebSocket endpoint. mountDevframe serves that file at each base by calling the host's mountConnectionMeta(base) alongside mountStatic.

This diagnostic is reported when a devframe with a servable cli.distDir is mounted on a DevframeHost that does not implement mountConnectionMeta. The SPA's ./__connection.json fetch then falls through to the host's HTML fallback, so the SPA cannot discover the endpoint and its panel stays empty or stuck loading — previously a silent failure.

The SPA can still connect when it shares an origin with the hub UI, by inheriting the connection meta from the parent window. Cross-origin, sandboxed, or directly-opened iframes have no such parent to inherit from.

Fix

Implement mountConnectionMeta(base) on your DevframeHost to serve the same connection meta you expose at the hub's own base:

const host: DevframeHost = {
  mountStatic(base, distDir) { /* serve files */ },
  mountConnectionMeta(base) {
    // serve `${base}__connection.json` → { backend: 'websocket', websocket: port }
  },
  resolveOrigin() { /* … */ },
  getStorageDir(scope) { /* … */ },
}

A static-snapshot host that bakes __connection.json into its served files can implement mountConnectionMeta as a no-op to acknowledge this intentionally and silence the diagnostic.

Source

• packages/hub/src/node/mount-devframe.ts — mountDevframe() emits this when a devframe with a servable distDir is mounted on a host lacking mountConnectionMeta.