---
outline: deep
---

# DF0033: Dev RPC Bridge Failed to Start

## Message

> Failed to start dev RPC bridge for "`{id}`": `{reason}`

## Cause

`viteDevBridge({ devMiddleware })` could not bring up the bridge dev server that pairs a host-served SPA (Vite, Nuxt, Astro, etc.) with devframe's RPC backend. Common reasons:

- The preferred port is in use and no fallback range was configured.
- Calling `def.setup(ctx)` threw — the devframe's own setup logic surfaced an error.
- A required peer (e.g. `get-port-please` or `h3`) is missing or mismatched.

This is a soft warning — the surrounding Vite dev server keeps running, but the host-served SPA will fail its `__connection.json` lookup until the bridge starts.

## Fix

- Pin a port via `cli.port` / `cli.portRange` on the devframe definition, or via `devMiddleware.port` on `viteDevBridge`.
- Inspect the `reason` (or the attached `cause`) for the underlying error — fix the setup function or free the port.
- For Nuxt: pass `devMiddleware: { port: <free-port> }` to the `@devframes/nuxt` module.

## Source

- [`packages/devframe/src/helpers/vite.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/helpers/vite.ts) — `viteDevBridge({ devMiddleware })` logs `DF0033` when port resolution or `createDevServer` throws during `configureServer`.
