---
title: "DF0052: HTTP Server Failed to Listen"
description: "Failed to listen on {host}:{port}: {reason}"
canonical_url: "https://devfra.me/errors/df0052"
---
# DF0052: HTTP Server Failed to Listen

> Failed to listen on \{host}:\{port}: \{reason}

## Message

> Failed to listen on `{host}:{port}`: `{reason}`

## Cause

The instance shell's HTTP server failed to bind `host:port`, most commonly `EADDRINUSE` (another process, often a previously running devframe, holds the port) or `EACCES` (insufficient permissions on a privileged port). The WS RPC transport is torn down before this surfaces, so nothing leaks.

## Example

```ts
// A previous instance is still bound to 4096:
// await createDevServer(def, { host: 'localhost', port: 4096 }) → DF0052
```

## Fix

- Free the port, or pick another via `--port`, `cli.port` / `cli.portRange` on the definition, or `port` on `devframeViteBridge` (`@devframes/vite`).
- The original node error is available as `error.cause`; check `error.cause.code` (e.g. `'EADDRINUSE'`) to branch on the failure kind programmatically.

## Source

- [`packages/devframe/src/node/instance-shell.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-shell.ts): the instance shell's HTTP+WS binding throws this when its owned HTTP server's `listen()` fails.


## Sitemap

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