---
title: "DF0056: Instance Advertises an External WebSocket Endpoint"
description: "This instance advertises an external WebSocket endpoint ({url}), so it serves no socket of its own."
canonical_url: "https://devfra.me/errors/df0056"
---
# DF0056: Instance Advertises an External WebSocket Endpoint

> This instance advertises an external WebSocket endpoint (\{url}), so it serves no socket of its own.

## Message

> This instance advertises an external WebSocket endpoint (`{url}`), so it serves no socket of its own.

## Cause

`ws.url` alone is the advertise-only tier: `__connection.json` names a fully-qualified endpoint the browser dials verbatim, and the server behind that URL owns the transport and its auth. This instance builds neither, so there is no socket for `attach(server)` / `handleUpgrade(req, socket, head)` to feed.

## Example

```ts
import { initDevframe } from 'devframe/initiate'

const relayed = initDevframe(def, {
  base: '/__my-tool/',
  ws: { url: 'wss://devtools.example.com/relay/__ws' },
})
relayed.attach(myServer) // ✗ throws DF0056: an external server owns the socket

// ✓ Serve the socket here, advertised through the relay (the tunnel pattern).
const tunnelled = initDevframe(def, {
  base: '/__my-tool/',
  ws: { url: 'wss://devtools.example.com/relay/__ws', sidecar: true },
})
```

## Fix

Drop `ws.url` to have the instance serve the socket, or pair it with `server` / `ws.port` / `ws.sidecar` for the tunnel pattern: a local binding that the advertised relay forwards to.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the shared instance shell throws this from `attach` / `handleUpgrade` when the resolved tier is `external`, for both `initDevframe` and `initHub`.


## Sitemap

See the full [sitemap](https://devfra.me/sitemap.md) for all pages.