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 → likely cause → fix, so scan for what you’re 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.

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.

Does autocomplete cost credits?

No. Credits meter agentic work — the requests where the agent plans, edits files, and runs commands. Inline completion isn’t that. Simple agentic asks can also cost less than a full credit. The pricing page has the current definition in writing.

Can I use Kiro offline?

No. The models run in the cloud, so anything agentic needs a connection. The IDE is built on Code OSS, so the editor itself still opens and edits files, but the part you installed it for won’t work on a plane.

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.

Which model does the Free tier get?

The pricing page lists Sonnet 4.5 plus the open-weight models for Free, along with 50 credits a month. Paid tiers open up the wider lineup. Model availability moves faster than most things in Kiro, so check kiro.dev/pricing rather than trusting any page’s snapshot.

Why can’t I open Kiro Web?

Kiro Web is still a preview: it’s on paid plans rather than Free, and it currently runs in the US region. It connects to GitHub and GitLab repositories. If the browser app rejects you while the IDE works fine, plan and region are the first two things to check, not your account.

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