Troubleshooting

If something goes wrong during the workshop, check this page for common issues and solutions.

"command not found: brew"

Problem: You installed Homebrew, but the Terminal cannot find it.

Solution: If you have an Apple Silicon Mac (M1/M2/M3/M4), run these two commands:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

eval "$(/opt/homebrew/bin/brew shellenv)"

Then try brew --version again. If it still does not work, close Terminal completely and reopen it.

"command not found: node"

Problem: Node.js is not installed or not in your PATH.

Solution: Install it with Homebrew:

brew install node

Then verify with node --version.

"command not found: pnpm"

Problem: pnpm is not installed globally.

Solution: Install it:

npm install -g pnpm

If npm is also not found, you need to install Node.js first (see above).

"command not found: git"

Problem: Git is not installed.

Solution: Run this command, which will trigger the Xcode Command Line Tools installer:

git --version

Click Install in the dialog that appears. Alternatively, install with Homebrew:

brew install git

"permission denied" errors

Problem: The Terminal says you do not have permission to do something.

Solution: Try running the command with sudo in front of it:

sudo npm install -g pnpm

You will be asked for your Mac password. This gives the command elevated (administrator) permissions.

"Port 5173 is already in use"

Problem: You tried to run pnpm dev but something is already using port 5173.

Solution: You probably have another instance of the dev server running. Either:

1. Find the other Terminal window or Kiro terminal where the server is running, and press Ctrl + C to stop it
2. Or, close all Terminal windows, reopen Terminal, navigate to the project, and run pnpm dev again

The page is blank or shows an error in the browser

Problem: After making a change with Kiro, the page shows a white screen or a red error overlay.

Solution:

1. Read the error message in the browser — it often tells you which file has the problem
2. In Kiro, undo the last change with Cmd + Z
3. Try a simpler version of your prompt
4. If the error persists, go to the Terminal running pnpm dev and press Ctrl + C to stop the server, then run pnpm dev again

Kiro is not responding to prompts

Problem: You type a prompt in Kiro but nothing happens.

Solution:

1. Check your internet connection — Kiro needs internet access to process prompts
2. Make sure you are signed in (check the bottom of the Kiro window)
3. Try closing and reopening Kiro
4. If the issue persists, check kiro.dev for any service status updates

"pnpm install" is taking too long or failing

Problem: The dependency installation is stuck or showing errors.

Solution:

1. Make sure you have a stable internet connection
2. Try deleting the node_modules folder and running pnpm install again:

rm -rf node_modules
pnpm install

3. If you see permission errors, try running Terminal as an administrator or check that your user account owns the project folder

Still stuck?

If your issue is not listed here, ask your workshop facilitator for help. Make sure to share:

1. The exact error message you see
2. The command you ran (or the prompt you typed in Kiro)
3. Which step of the workshop you are on