Troubleshooting

Fix common installation, terminal, timer, and Mintlify docs issues.

Troubleshooting

This page covers common problems and quick fixes.

pomodoro is not recognized

If your terminal says pomodoro is not recognized, the CLI is not on your PATH.

Try closing and reopening your terminal first.

If you installed with npm, reinstall:

npm install -g go-pomodoro

On Windows PowerShell, use:

npm.cmd install -g go-pomodoro

Then check:

pomodoro version

PowerShell blocks npm

PowerShell may show an error like:

running scripts is disabled on this system

Use npm.cmd instead of npm:

npm.cmd install -g go-pomodoro

This avoids the blocked PowerShell script wrapper.

No active timer

If pomodoro status prints:

No active timer

start a session:

pomodoro start

Then check again:

pomodoro status

Stop a stuck timer

If a timer looks stuck, stop it:

pomodoro stop

Then start a new one:

pomodoro start

No sessions yet

If pomodoro sessions prints:

No sessions yet.

complete a focus session first.

Start a short test session:

pomodoro start -m 1

After it finishes, run:

pomodoro sessions

Coach says to complete sessions first

pomodoro coach needs recent sessions.

Run:

pomodoro sessions

If no sessions appear, complete a few focus sessions before using coaching.

AI tips are not showing

AI features need GROQ_API_KEY.

On macOS or Linux:

export GROQ_API_KEY="your_api_key_here"

On Windows PowerShell:

setx GROQ_API_KEY "your_api_key_here"

Open a new terminal after using setx.

The timer still works without AI.

pomodoro update fails

If you see an error saying the development build cannot update, you are running a dev build.

Use your original install method instead:

npm install -g go-pomodoro

or:

go install github.com/imSaikirann/go-pomodoro@latest

Mintlify: mintlify is not recognized

Mintlify now uses the mint CLI.

From the docs folder, run:

npx.cmd mint dev

or install it globally:

npm.cmd install -g mint
mint dev

Run Mintlify from the folder that contains docs.json.

Mintlify: invalid docs.json

The docs site needs these required fields:

• name
• theme
• colors.primary
• navigation

This project includes those fields in docs.json.

If you edit the file and Mintlify fails, check that colors.primary is still a valid hex color:

"colors": {
  "primary": "#16A34A"
}