Troubleshooting & FAQ

Most Kiro problems are not mysterious: they cluster into five areas (install, sign-in, MCP, context, credits), and each area has a short list of usual causes. This chapter is arranged symptom, then likely cause, then fix, so scan for what you are seeing rather than reading it end to end.

Start by updating

Before debugging anything, check which version you’re running and update it. A striking number of known symptoms have a fix date attached to a specific release: the compaction loop that produced context-limit errors was fixed in IDE v1.0.138 (July 2026); corporate-proxy reliability improved in IDE v1.0.182; interrupted responses retry automatically in CLI v2.14 and recover automatically in IDE v1.0.182. If you’re on something older, the bug you’re chasing may already be closed.

Error messages, word for word

These are the strings people paste into a search box. For each one, the honest position: Kiro’s documentation does not publish a cause for these messages, so what follows is the sequence of steps that usually resolves them, ordered cheapest first. Work down the list rather than picking one.

The general order, which applies to all four:

1. Update. Check your IDE or CLI version and update it. Several past symptoms have a fix attached to a specific release.
2. Retry once. Transient failures are common and the CLI already retries some of them for you.
3. Start a fresh session, or run /compact in the CLI to shrink the conversation.
4. Check the network path: proxy, VPN, TLS inspection, firewall.
5. Sign out and back in, with the same identity provider you originally used.
6. Check kiro.dev/changelog for a matching entry.
7. Report it with your surface, exact version, and a saved session.

”Improperly formed request”

The wording suggests a request Kiro’s service would not accept, but no documented cause exists, so treat that as a hint rather than a diagnosis. The steps below assume the most reachable explanation, which is something unusual in the request context: an enormous file pulled in by a glob, a pasted blob, or a tool result that came back oddly.

Steps in order: update first; retry the same prompt once; run /context show in the CLI to see what is loaded and /context remove or /context clear to trim anything surprising; start a new session; then check the changelog. If it reproduces on a small, clean session, that is a good bug report.

”Context limit exceeded unexpectedly. Please try again.”

The word doing the work here is unexpectedly. A plain context-limit message means the conversation genuinely filled up; this one means Kiro did not expect it to.

Update first, and mean it: a compaction loop that caused context-limit errors was fixed in IDE v1.0.138 (July 2026), so on anything older you may be debugging a closed bug. Then run /context show, which reports token usage per file and, since CLI v2.16, per tool. If one glob pulled in a build directory or a lockfile you will see it immediately. Trim, then use /compact to summarize older history, or start a new session. Remember that compaction is one-way: the history before the compaction point is not recoverable.

”Your connection was interrupted. Please try again in a moment.”

The message names the network, and the fixes that have shipped for it are network fixes, so start there. Update first, because CLI v2.19.0 (August 2026) added automatic recovery for exactly this class of failure: retries for throttling, 5xx responses, and dropped connections, an idle watchdog that warns at 60 seconds and cancels at 300, and a 60-minute streaming timeout. IDE v1.0.182 improved corporate-proxy reliability and v1.0.395 keeps agent turns going when the network briefly drops.

If updating does not settle it, the network is the suspect: corporate proxy, VPN, or TLS inspection rewriting certificates. This usually becomes an IT conversation rather than a Kiro one, and the two questions worth asking are whether kiro.dev domains are allowed and whether TLS inspection is in the path. The CLI timeouts are configurable through api.streamIdleSoftTimeout, api.streamIdleHardTimeout, and api.timeout if your work genuinely needs longer.

”Unexpected error”

The catch-all, which by definition has no single cause. Treat it as a prompt to gather information rather than to guess.

Work the general list: update, retry once, new session, check the network, sign out and back in. Then narrow it. Does it happen in one workspace or all of them? With one MCP server disabled? On a small prompt? In the IDE, the output channels (including Kiro - MCP Logs) often carry a more specific message than the one in the chat panel. Whatever you learn belongs in the bug report.

Install problems

Symptom	Likely cause	Fix
CLI won’t install on Windows 10	The CLI requires Windows 11 — narrower than the IDE, which supports Windows 10 and 11	Use the IDE on that machine, or move to Windows 11
The install command isn’t recognized on Windows	irm 'https://cli.kiro.dev/install.ps1' | iex is PowerShell syntax	Run it in PowerShell or Windows Terminal, not Command Prompt
Nothing installs on a Windows ARM laptop	Windows support is 64-bit x86 only; ARM is not supported	No workaround — use an x86-64 machine
Linux IDE won’t launch	The IDE needs glibc The GNU C Library, the low-level system library most Linux desktop software links against. Its version is set by your distribution, not by the app. 2.39 or newer	Ubuntu 24+, Debian 13+, Fedora 40+, Arch, or Mint 22+
CLI runs fine on a box where the IDE won’t	Expected: the CLI needs only glibc 2.34+, with a musl fallback	On older distros, the CLI is the surface that works
You’d rather not pipe an install script to bash	—	Linux also ships AppImage, .deb, and zip packages

The asymmetry between surfaces is the single most common install surprise. People assume “Kiro supports my machine” is one fact; it’s two. The IDE is the more permissive of the two on Windows (10 and 11); the CLI is the more permissive on Linux (glibc 2.34 versus 2.39). On an older server or an LTS box that’s a few releases behind, reach for the CLI first.

Sign-in problems

Symptom	Likely cause	Fix
Install finishes, browser never opens	The CLI install ends with a browser-based sign-in step, which can’t complete on an SSH session or headless server	Use the documented headless path: authenticate with the KIRO_API_KEY environment variable
Sign-in stalls or responses cut out on a work laptop	Corporate proxy or TLS inspection	Update first — IDE v1.0.182 (July 2026) specifically improved corporate-proxy reliability
Signed in, but all your settings and history are gone	You used a different sign-in method than last time	Sign out and back in with the original provider

The headless case. The install script’s last step opens a browser. On a remote box, a container, or a CI runner there is no browser to open, so that flow has nowhere to finish. The supported route in those environments is the KIRO_API_KEY environment variable, sourced from your CI secret store rather than committed anywhere. That’s the same mechanism the CLI guide uses for headless runs.

The proxy case. Updating is the first move, because the July 2026 IDE release named proxy environments explicitly. If updating doesn’t clear it, this becomes an IT conversation rather than a Kiro one: in practice, it’s worth asking whether the proxy allows kiro.dev domains, and whether TLS inspection is rewriting certificates on that traffic.

The identity case. Kiro’s sign-in options are Google, GitHub, AWS Builder ID, and organization identity or SSO. A common gotcha: those are four different identities, not four doors into one account. If you signed up with GitHub in June and clicked “Google” in August, Kiro isn’t broken — you are logged into a different account, with its own settings, history, and credit balance. Worth checking before anything else when everything looks mysteriously empty.

MCP server problems

The first stop is always the same, and it’s not the config file. In the IDE, open the MCP servers panel and read each server’s connection status; then open the Kiro - MCP Logs output channel. A server that failed to start usually says why there, and that one look saves an hour of editing JSON on a hunch.

Symptom	Likely cause	Fix
Server shows as not connected, and it needs a login	The server uses OAuth and hasn’t been authorized	CLI: /mcp auth (v2.11.0+). The IDE handles MCP OAuth automatically since v1.0.116
A local server never starts	Local servers run a command with args — if the command is npx, Node has to exist and be on PATH	Worth checking that the exact command runs in a plain terminal first
A CI job hangs instead of failing	The pipeline is waiting on an MCP server that will never connect	Add --require-mcp-startup so the run fails fast
A server misbehaves in one project only	Workspace .kiro/settings/mcp.json takes precedence over the user-level file	Check the workspace file for an override you forgot about
A server starts but authentication fails	An ${ENV_VAR} reference in config resolving to nothing	Confirm the variable is set in the environment Kiro was launched from

The precedence rule deserves its own moment, because it produces the most confusing MCP bug there is: the same server, configured once, behaving differently depending on which folder you opened. Workspace config wins over user config. If a server works everywhere except one project, look in that project’s .kiro/settings/mcp.json before you look anywhere else.

Auth state is also cleanable: the CLI has /mcp cancel-auth to abandon a pending authorization and /mcp logout to drop saved credentials, which is the reset button when a half-finished OAuth flow leaves a server stuck.

Two config fields are worth remembering while you’re in there. disabled turns a server off without deleting its entry, which is the clean way to isolate one suspect server instead of commenting out JSON. disabledTools removes individual tools from an otherwise working server — useful when one noisy tool is the actual problem.

Context-limit and session problems

Context-limit errors mid-session. First check whether it’s real. /context show reports what’s loaded with token usage per file, and since CLI v2.16 it breaks usage down per tool as well. If one glob pulled in a build directory or a lockfile, you’ll see it immediately. Trim with /context remove for a single rule or /context clear to start over, then re-add only what the task needs.

Second, check your version. A compaction loop that caused context-limit errors was fixed in IDE v1.0.138 (July 2026). If you’re seeing these errors on an older IDE, update before rearranging your context — you may be debugging a fixed bug.

Interrupted or dropped responses. The CLI retries interrupted model responses automatically since v2.14, and the IDE recovers from them automatically since v1.0.182. Both fixes landed in July 2026. On anything older, this is an update, not a workaround.

A session you can’t find. Sessions persist, so the answer is almost never “start over”:

Where	How to get back
CLI, same directory	kiro-cli chat --resume
CLI, a specific session	kiro-cli chat --resume-id <SESSION_ID>
CLI, not sure which	kiro-cli chat --resume-picker
IDE	The searchable session history panel (v1.0.182+)
Inside a session that went wrong	Roll back to a checkpoint

Checkpoints are the tool for the other kind of loss: not a missing session, but a present one full of changes you don’t want. They restore the session state, which makes them excellent mid-flight and no substitute for git afterwards.

Credit surprises

If your balance drained faster than expected, the causes are usually mundane: an expensive model left selected (the Opus tier carries a 2.2x credit multiplier against Auto’s 1.0x), an unattended agent loop that kept working while nobody watched, or the assumption that unused credits carry into next month — they don’t.

The Credits & Pricing chapter covers the mechanics properly, including which knobs actually change consumption. For current numbers, kiro.dev/pricing is the authority.

Two habits prevent most of the surprise, both practice rather than documented behavior. Glance at which model is selected before starting a long agentic task, since the multiplier applies to everything that follows. And treat headless or scheduled runs as spending processes: give them a narrow prompt, a restricted tool set, and something that stops them.

Frequently asked questions

Is my code used to train models?

This is exactly the question you should not take from a third-party tutorial, including this one. Kiro’s privacy and security documentation at kiro.dev/docs states the current policy, and it can differ by tier and by surface. Read it there, and if you’re at a company, read it alongside your own data policy.

Do the old q / Q Developer CLI commands still work?

Yes. Kiro CLI is the official successor to Amazon Q Developer CLI, and the q entry points were preserved through the transition; configuration migrates from ~/.aws/amazonq to ~/.kiro. The History chapter explains the timeline, which is also why so many older blog posts use different command names.

I can’t open Kiro Web, or I can’t start a cloud session.

Two different gates that look alike. Kiro Web reached general availability on September 1, 2026 and runs on Pro, Pro+, Pro Max, and Power, with GitHub and GitLab; it is not on Free, and with AWS Identity Center sign-in it runs in us-east-1 only. Cloud sessions add their own limits: a paid plan, US East (N. Virginia), at most 10 running at once, and CLI v2.17.0 or IDE v1.0.293 at minimum. Organizations on AWS Identity Center, Okta, or Microsoft Entra ID need an administrator to enable cloud sessions, and in the CLI they ship opt-in for enterprise administrators (v2.18.0), so a working personal setup proves nothing about your work account.

Kiro Crew won’t start, or I can’t reach its dashboard.

Run kirocrew doctor first; it exists to verify the installation. The gateway serves http://localhost:5476, and the dashboard binds to loopback only by default, so on a remote host you reach it through a tunnel (ssh -L 5476:localhost:5476 user@host) rather than by opening the port. Check the prerequisites too: Python 3.12 or newer, which is the minimum since Crew 0.6.0 (September 2026) and a common cause of a failed upgrade on a box still running 3.10, and kiro-cli for model access, which the desktop app installs on first launch. On a remote box, plan for about 10 GB of RAM minimum and 16 GB recommended. Kiro Crew has the full setup.

My long CLI run keeps dying partway through.

Update first. CLI v2.19.0 (August 2026) added automatic recovery for exactly this: retries for throttling, 5xx errors, and dropped connections, plus an idle watchdog that warns at 60 seconds and cancels at 300, and a 60-minute streaming timeout so a long response is not cut off early. If the defaults do not fit your work, they are configurable through api.streamIdleSoftTimeout, api.streamIdleHardTimeout, and api.timeout.

Something behaves differently than this site says. Who’s right?

The changelog. Every page here carries a last-reviewed date for exactly this reason.

Where do I report a bug?

The kirodotdev GitHub organization is the public home for Kiro repositories and issues, and kiro.dev/docs points to current support channels. Before filing, note your surface (IDE, CLI, or Web) and exact version — most of this chapter exists because versions matter.

Where help lives

Source	Use it for
kiro.dev/docs	The authoritative reference for every feature, including privacy and security
kiro.dev/changelog	What changed and when — the referee for any behavior disagreement
github.com/kirodotdev	Repositories, issues, and community reports
kiro.dev/pricing	Current plans, credits, and model availability