---
outline: deep
---

# DF8204: Terminal Session Cannot Be Controlled

## Message

> Terminal session "`{id}`" cannot be controlled (no lifecycle handle)

## Cause

`hub:terminals:terminate` or `hub:terminals:restart` was called for a session
that carries no lifecycle handle. Sessions added with a bare
`ctx.terminals.register()` are just a descriptor plus an output stream — they
expose no `terminate()` / `restart()`. Only sessions spawned via
`ctx.terminals.startChildProcess()` or `ctx.terminals.startPtySession()` own
their process and can be terminated or restarted.

## Fix

- Spawn the session via `ctx.terminals.startChildProcess(executeOptions, terminal)`
  or `ctx.terminals.startPtySession(executeOptions, terminal)` so it owns a
  process the hub can control.
- For a bare `register()` session, drive its lifecycle from whatever owns the
  underlying process; `hub:terminals:remove` still drops it from the registry.

## Source

- [`packages/hub/src/node/rpc-builtins.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/rpc-builtins.ts) — the `hub:terminals:terminate` / `hub:terminals:restart` handlers throw this when the resolved session has no `terminate` handle.
