CliDeck
PlatformLog in
Workspace

Fixing “[screen is terminating]” on macOS: A Checklist That Actually Works

Serial Console
#Serial Console#serial-console
← Back to Blog

Short answer

On macOS, [screen is terminating] usually means screen could not keep the target port or session open. Confirm the /dev/cu.* path, release any process holding it, check permissions and adapter state, and then reconnect with the expected console settings.

What “[screen is terminating]” means on macOS

In most cases, this line means screen started and then immediately exited because it couldn’t open what it needed (a port or a socket), hit a permissions problem, ran a short command that ended instantly, or ran into an environment issue (socket directory, TERM, or a busy device).

It’s not “screen being broken” by itself. It’s a symptom that something failed before the session could stay alive.

If you want a more predictable day-to-day workflow with multiple devices, consistent session history, and logs, that’s exactly the type of problem CliDeck is built to solve: CliDeck Workspace.

The 3–5 minute checklist (follow in order)

Most people fix this within the first few steps.

1) Make sure you’re running the right command

The most common Google mistake is forgetting the dash:

  • Wrong: screen ls This is interpreted as “run ls inside screen.” ls finishes instantly, and you see [screen is terminating].

  • Correct:

screen -ls

Also test basic functionality:

screen

If screen works without arguments but fails with your serial command, the issue is usually the port, permissions, or arguments.

2) For serial consoles on macOS, use /dev/cu.* (not /dev/tty.*)

macOS often exposes the same adapter as two device names. For console sessions, you almost always want /dev/cu.*.

Check:

ls -1 /dev/cu.*

Correct example:

screen /dev/cu.usbserial-XXXX 9600

If you used /dev/tty.* and things feel odd or stuck, switch to the matching /dev/cu.*.

3) Confirm the port actually exists (and the name didn’t change)

It’s easy for the suffix to change when you move USB ports or docks.

ls -1 /dev/cu.*

Look for entries like cu.usbserial-*, cu.SLAB_USBtoUART, cu.wchusbserial*, or cu.usbmodem*.

4) Check whether another app is already using the port

If the port is open in an IDE, serial monitor, another terminal, or a previous screen/cu session, screen can terminate immediately.

Fast check:

lsof /dev/cu.usbserial-XXXX

If you see processes listed, close them and retry.

5) Check permissions (and do a quick sudo test)

Sometimes it’s simply a permissions issue.

Check device permissions:

ls -l /dev/cu.usbserial-XXXX

Quick diagnostic test:

sudo screen /dev/cu.usbserial-XXXX 9600

If it works with sudo, the root cause is almost certainly permissions or policy. You can use sudo as a temporary workaround, or fix access according to your security requirements.

6) On Apple silicon, consider “Allow accessory to connect?” if the port never appears

If your adapter doesn’t show up in /dev/cu.* at all, the issue may be macOS accessory security (you need to allow the accessory). In that case, fix the accessory permission first, then return to screen.

7) If screen can’t create its socket directory, set SCREENDIR

If screen can’t create or use its socket directory (especially in unusual environments), a reliable fix is using a private directory under your home folder:

mkdir -p "$HOME/.screen"
chmod 700 "$HOME/.screen"
export SCREENDIR="$HOME/.screen"

Then retry:

screen -ls
screen

If this solves it, add the export SCREENDIR=... line to your shell profile so it persists.

8) Clear dead sessions and reconnect cleanly

List sessions:

screen -ls

If you see dead/broken entries, wipe them:

screen -wipe

If a session exists, reattach:

screen -r

If it’s “Attached” and you need to force takeover:

screen -d -r

To kill a specific session:

screen -X -S <session> quit

Where <session> is the name shown in screen -ls (for example 12345.pts-0.host).

9) If it only fails in one terminal, check TERM

This is less common, but it happens: screen may exit immediately in a specific terminal environment.

Quick test:

echo "$TERM"
TERM=xterm-256color screen

If that makes it stable, the issue is your terminal environment. The fix is adjusting TERM or your terminal configuration to something screen can handle consistently.

Serial console mini-checklist (for screen /dev/... 9600)

If screen immediately prints [screen is terminating] when you connect to a serial device:

  1. Confirm the port exists:
ls -1 /dev/cu.*
  1. Use /dev/cu.*:
screen /dev/cu.usbserial-XXXX 9600
  1. Confirm the port isn’t busy:
lsof /dev/cu.usbserial-XXXX
  1. Try the two most common baud rates:
screen /dev/cu.usbserial-XXXX 9600
screen /dev/cu.usbserial-XXXX 115200
  1. Quick permissions test:
sudo screen /dev/cu.usbserial-XXXX 9600

When it’s better not to fight screen

screen is a great offline tool and often the fastest option. But if you regularly manage multiple devices, need reliable logs, and want a cleaner workflow, it’s worth using a workspace that treats sessions and history as first-class features. That’s a core use case for CliDeck: CliDeck Features.

Bottom line

On macOS, “[screen is terminating]” is almost always fixed by one of these:

  • you typed screen ls instead of screen -ls,
  • you used /dev/tty.* instead of /dev/cu.*,
  • the port is already in use,
  • you don’t have permission to open the device,
  • screen socket directory issues (fixed with SCREENDIR),
  • a rare terminal environment mismatch (TERM).

And if you want to stop losing time to these recurring “small fires,” try CliDeck: CliDeck Workspace.

Who this is for

This guide is for network engineers, field technicians, remote hands, lab engineers, and system administrators who need to connect to, troubleshoot, log, or verify a serial console session on switches, routers, firewalls, appliances, servers, and other devices with console ports.

When to use this

Use this guide when:

  • You need direct console access to a switch, router, firewall, appliance, server, or lab device.
  • SSH or management-plane access is unavailable, unreliable, or not yet configured.
  • You need to troubleshoot a USB serial adapter, COM port, baud rate, or terminal session.

When not to use this

Do not use this guide when:

  • Do not use this guide as a substitute for vendor documentation, site policy, or a verified device-specific runbook when the operation is risky.
  • Do not continue if the console output suggests you are connected to the wrong device.

Quick checklist

  • Identify the device and console connector
  • Use the correct console cable or adapter
  • Find the correct serial port or COM port
  • Start with the expected baud rate and 8N1 settings
  • Press Enter to confirm the prompt
  • If output is unreadable, check baud rate and line settings
  • If the port will not open, check permissions, drivers, and whether another program is holding the port
  • Save useful session notes or logs when the work matters

Traditional cable vs CliDeck workflow

A traditional USB serial cable is still the simplest option for quick local work. CliDeck becomes useful when the console session needs browser access, notes, runbooks, sharing, logs, remote hands support, or a portable controller workflow.

Console Server Go can work like a wired USB serial adapter when connected by USB, but it also adds SSH Console on SSH-enabled firmware builds, browser Workspace, live sharing, 24h+ battery operation, OLED status, and magnetic rack mounting.

Workflow

  • Identify the device, connector, cable, adapter, and host operating system.
  • Find the correct serial port or COM port and confirm permissions or drivers.
  • Open the session with the expected baud rate and line settings, usually 8N1 unless documented otherwise.
  • Press Enter and verify the prompt before running commands.
  • Save notes or logs when the session supports a change, recovery, handoff, or evidence workflow.

Verification checklist

  • The detected serial port or COM port matches the connected adapter.
  • Baud rate, data bits, parity, stop bits, and flow control match the device expectation.
  • The terminal shows a readable prompt after pressing Enter.
  • No other terminal application is holding the port.
  • Useful notes or logs are saved when the work matters.

Common mistakes

  • Using the wrong cable or adapter for the console connector.
  • Opening the wrong COM port or /dev/cu.* device.
  • Assuming unreadable output means hardware failure before checking baud rate and 8N1 settings.
  • Leaving another terminal application attached to the port.

CliDeck workflow fit

A traditional USB serial cable is still the simplest option for quick local work. CliDeck becomes useful when the console session needs browser access, notes, runbooks, sharing, logs, remote hands support, or a portable controller workflow.

Console Server Go can work like a wired USB serial adapter when connected by USB, but it also adds SSH Console on SSH-enabled firmware builds, browser Workspace, live sharing, 24h+ battery operation, OLED status, and magnetic rack mounting.

FAQ

Is a USB serial cable still enough?

Yes, for simple local work where one engineer is sitting next to one device. CliDeck is more useful when the console session needs sharing, runbooks, browser Workspace, remote hands support, logs, or longer operational context.

What should I check first when serial output looks like garbage?

Check the baud rate, data bits, parity, stop bits, flow control, cable type, and whether the device is actually using the expected console port.

Can CliDeck help with serial console work?

Yes. CliDeck Workspace helps organize terminal sessions, notes, runbooks, and logs. Console Server Go adds portable rack-side access, and Net Controller supports larger batch workflows.

Related guides