This page routes a Kiro CLI symptom to the page that owns the fix. It adds no steps of its own: find your symptom, then follow the link.
| Symptom | Where the fix lives |
|---|---|
| The session opens with Kiro CLI V3 is here and you expected V3 | Confirm which harness is running, then Save a default harness |
A launch with --classic, --legacy-ui, or chat.ui shows a message that offers Continue with V3 | If a launch still selects Classic |
| On Linux, a launch that still selects Classic says this machine can't run the 3.0 agent | Linux machines with older glibc |
| Kiro CLI prints a reinstall message because the terminal UI is missing | Installation |
| A script or pipeline ran on V2 when you expected V3 | Scripts and CI |
| An editor connected over ACP started on the wrong harness | ACP clients |
| You want V2 back | Return to V2 |
| The terminal UI does not load or renders incorrectly | Terminal UI troubleshooting |
| Symptom | Where the fix lives |
|---|---|
| V2 cannot open a session you created in V3 | Start V3 and keep V2 sessions available |
| A custom agent is skipped or shows an upgrade warning | Reviewing diagnostics |
| A custom agent does not load or behaves unexpectedly | Custom agents troubleshooting |
| Hooks from Kiro CLI 2.x no longer fire | Hooks migration |
| Trust settings from Kiro CLI 2.x no longer apply | Permissions migration |
| An ACP client lost capabilities after moving to V3 | Validate the migrated client |
| An MCP server fails to start or its tools are missing | MCP troubleshooting |
| A setting is rejected or has no effect | Troubleshooting settings |
A saved session is missing from /sessions | Session management troubleshooting |
When no page above covers your symptom, collect a diagnostic report and file an issue:
kiro-cli diagnostic gathers the details Kiro needs.kiro-cli issue opens a bug report.If your symptom started after an upgrade from Kiro CLI 2.x, work through Upgrade from CLI 2.x in order.
Troubleshooting