Skip to main content

🛠️ Troubleshooting

Things not working? Don't worry — most issues have a quick fix. Find your problem below and follow the steps.

Ask Your Mentor First

If you're stuck during the hackathon, grab your mentor before spending too long on a fix. They've seen most of these issues before and can help fast.

🔒 Security Warning When Opening Kiro​

Your computer might block Kiro because it was downloaded from the internet. The fix depends on your operating system.

Problem: macOS Gatekeeper shows a message like "Kiro can't be opened because it is from an unidentified developer" or "Kiro is damaged and can't be opened."

Fix:

  1. Open System Settings → Privacy & Security.
  2. Scroll down to the Security section.
  3. You should see a message about Kiro being blocked. Click Open Anyway.
  4. A confirmation dialog will appear — click Open.
  5. Kiro should now launch normally.
tip

You only need to do this once. macOS will remember your choice and won't block Kiro again.

💻 ARM Device Incompatibility​

Problem: Kiro won't install or crashes immediately on a Windows device.

Why: Kiro requires Windows 64-bit (x64). Windows on ARM (some Surface Pro models, Snapdragon-powered laptops) is not supported.

Fix: Switch to a different computer running macOS (Intel or Apple Silicon) or Windows 64-bit (x64). Linux works too but isn't covered by the Setup Guide.

How to check if your device is ARM

On Windows, press Win + I → System → About and look at System type. "64-bit operating system, x64-based processor" = good. "ARM-based processor" = won't work with Kiro.

🐢 Kiro Slow or Frozen​

Problem: Kiro takes ages to respond, the chat won't move, or the whole interface is frozen.

Fix:

  1. Wait 30 seconds. Big responses can take a moment. Don't interrupt.
  2. Check your internet. Kiro needs an active connection for every AI request — try loading a website in Chrome to confirm you're online.
  3. Close other apps. Browsers with lots of tabs, video calls, and big downloads compete for memory. Close anything you don't need.
  4. Restart Kiro. Quit and reopen:
  1. Press Cmd + Q to quit Kiro.
  2. If it won't quit, open Activity Monitor (search in Spotlight), find "Kiro", and force-quit it.
  3. Reopen Kiro from Applications.
If the whole room is slow

It's almost certainly a network issue, not a device issue. Tell your mentor — there may be a better network to switch to.

🌐 App Preview Not Working in the Browser​

Problem: You opened Chrome and went to the preview URL (usually http://localhost:3000) but the page is blank, shows an error, or won't load.

Fix:

  1. Make sure the app is actually running. Check the Kiro terminal or chat — it should show a message like "Server running on http://localhost:3000". If you don't see that, ask Kiro to start the app.
  2. Hard refresh the page. Sometimes the browser is showing a cached version:
    • Mac: Press Cmd + Shift + R
    • Windows: Press Ctrl + Shift + R
  3. Check the URL. Make sure you're going to exactly the address Kiro told you — including the port number (the :3000 part).
  4. Try a different port. If something else is using port 3000, Kiro may start the app on a different port (like 3001 or 3002). Check the terminal output for the actual URL.
tip

If you see a message like "This site can't be reached" or "ERR_CONNECTION_REFUSED", the app server probably isn't running. Go back to Kiro and ask it to start the development server.

🤖 "Invalid Model ID" Error in Kiro Chat​

Problem: You send a prompt in Kiro's Chat Panel and get back an error like "Invalid model ID" instead of a real response.

Why: Kiro couldn't reach a working AI model with the current setting. This is usually a transient backend issue, not a problem with your prompt or your project.

Fix:

  1. Switch the model manually. In the Chat Panel, look for the model selector near the input box. If it's set to Auto, change it to a specific model (e.g. Claude Sonnet). Try your prompt again.
  2. Resend the prompt. Sometimes the next request just works.
  3. Restart Kiro. Quit (Cmd + Q on Mac, Alt + F4 on Windows) and reopen. Send the prompt again.
  4. Check your internet. Kiro needs a working connection for every AI request.
Flag it if it's room-wide

If multiple teams hit this at the same time, tell your mentor — it's likely an upstream outage and the AWS technical mentor will want to know.

↩️ Resetting Broken Code​

Problem: You asked Kiro to make changes and now the app is broken — errors everywhere, nothing works.

Fix:

Don't panic. You have options:

  1. Ask Kiro to fix it. Type something like:

    The app is broken after the last change. Can you undo the last change
    and get it working again?

  2. Use Undo. If the change just happened, press Cmd + Z (Mac) or Ctrl + Z (Windows) multiple times in the affected file to undo recent edits.

  3. Start fresh from a clean copy. If things are really messed up, ask your mentor — they can help you reset to a fresh copy of the project (or scaffold a new one with Kiro) without losing your team's work.

tip

This is why starting small matters. One change at a time, test after each one — it's much easier to spot what broke.

🔑 Unable to Sign In​

Problem: Kiro asks you to sign in but the sign-in page won't load, gives an error like "This app is blocked by your administrator", or loops without signing you in.

Fix (try in this order):

  1. Use a personal @gmail.com, not your school email. This is the #1 cause of sign-in failures. School Google Workspace accounts often block third-party apps like Kiro. A standard personal Gmail almost always works.

  2. Check your internet. Try loading google.com in Chrome. If that fails, you're offline.

  3. Try a different Google account. If you're already signed in to multiple Google accounts in your browser, Kiro may be picking the wrong one. Sign out of all of them first, then try again.

  4. Network blocking auth. If multiple students hit this at the same time, the school network may be blocking sign-in. Tell your mentor — they can flag it to IT or the event organisers. The domains that need to be allowed are kiro.dev and Google sign-in.

  5. Last resort — clear Kiro's sign-in state. Only do this if all of the above failed and your mentor agrees:

  1. Quit Kiro (Cmd + Q).
  2. Open Finder, press Cmd + Shift + G, and paste: ~/Library/Application Support/Kiro
  3. Rename the folder to Kiro-backup (so you can put it back if needed).
  4. Reopen Kiro and try signing in again.

🆘 Still Stuck?​

If none of the fixes above work:

  1. Ask your mentor — they can escalate to the event organisers.
  2. Pair up — join another team's computer temporarily while the issue gets sorted out.
  3. Check the Resources page for additional links and support contacts.

Don't let a tech issue stop you — there's always a way to keep going. 💪

Enjoying the docs? Good.

The docs are the how. The newsletter is the what... as in, what the f*** — AI, power, Big Tech and the tech industry, through a Pasifika lens, from an engineer who's spent twenty-plus years working inside the machine. Fortnightly. No filter.

Leave whenever.

Get the newsletter →