CliDeck
WORKSPACE

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

← Back to Blog

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.