Startup failures now show a readable error message

If Claude Code fails while starting up, it now exits with a message beginning 'Claude Code could not start:' instead of an unhandled error

You'll noticeTier: how much it should matter to you

2Useful: my rating, 1 to 5

1Signal: worth watching, 1 to 5

ElsewhereArea: what it touches

Bug FixesKind: in v2.1.314, 30 Oct 26

Bug FixesSection of the release

What

If something goes wrong while Claude Code is setting itself up at startup, it now catches the failure and exits with a message that starts with "Claude Code could not start:" followed by the reason. This happens in most modes. Before, such a failure was not caught.

Some migrations, steps that update older saved data to a newer format, can now be put off and run later as one batch.

The startup check on --plugin-dir, --plugin-url and --agents when plugins are also given through CLAUDE_CODE_PLUGIN_DIRS works as before.

Why

A failed startup now tells you what went wrong in plain text, instead of ending with a raw error.

How sure we are

One source agreesOne thing we can check says the same as this entry.

Anthropic's release notes agreeFixed model switching being refused on machines with managed plugin settings when one of your own --plugin-dir or --plugin-url plugins had a…

See this entry in the whole of v2.1.314 →

The build it came inv2.1.314

30 Oct 2026 · 430 entries, this one is #274.

Use it now17
You'll notice259
Nothing to try yet19
Under the hood135

Either side of it

v2.1.312Older

Open the release →

Names in this entry

cli--plugin-dir
Load a plugin from a directory or .zip archive, or several from a folder of plugins, for this session only. Each flag takes one path. Repeat the flag for more paths: --plugin-dir A --plugin-dir B.zip. Passing a folder of plugins requires Claude Code v2.1.265 or later
cli--plugin-url
Fetch a plugin .zip archive from a URL for this session only. Repeat the flag for multiple plugins, or pass space-separated URLs in a single quoted value
cli--agents
Define custom subagents dynamically via JSON. Accepts the fields listed for CLI-defined subagents. With --print, the value can instead be the path to a JSON file holding the object; the file form requires Claude Code v2.1.281 or later. Claude Code validates the value at startup and exits on an invalid one; see Invalid --agents configuration for the message and for the flags and environment variable that skip the validation. Validation requires Claude Code v2.1.242 or later
envCLAUDE_CODE_PLUGIN_DIRS
New CLAUDE_CODE_PLUGIN_DIRS environment variable lets you register extra plugin directories without --plugin-dir flags

Anthropic's note

Upstream's own release notes for v2.1.314 name something this entry names, so the two are probably about the same change. Probably: the pairing is made on a shared name rather than on the words around it.

Fixed model switching being refused on machines with managed plugin settings when one of your own --plugin-dir or --plugin-url plugins had a broken manifest or failed to download

Is this right?