Troubleshooting
Fix common harumi CLI errors: run the quick checks, see whether the platform is down, look up frequent errors, and reset local state.
Quick checks
Confirm you're logged in
harumi whoamiIf this errors, run harumi login (or harumi login --signup for a brand-new
email).
Confirm the directory is bound
run, runs, check, skills add, datasources, schedules, and secrets
need a project. Either run from a directory containing .harumi/config.json
(written by harumi new/import/clone/link) or pass --project <PROJECT_ID>.
Check platform status
If several commands fail at once, or a command that used to work starts failing with connection errors or HTTP 5xx responses, check status.harumi.io before debugging locally. It shows a live check for each part of the platform:
| Monitor | What it covers |
|---|---|
Platform | The Harumi web app |
Harumi AI | Harumi AI Chat, including its connection to the database and the Harumi API |
API | The Harumi API the CLI talks to, including its database, cache, scheduler, and git backend |
Scheduling | The scheduler that fires scheduled runs |
Git | Project repositories (import, clone, git push harumi) |
MCP | The connection from ChatGPT and Claude |
Docs | This documentation site |
Sandbox (ephemeral) | Interactive code execution |
Sandbox (scheduled) | Scheduled and background runs |
Sandbox (apps) | Hosted project apps |
Database | The platform database |
If a monitor is down, wait for it to recover and retry; there is nothing to fix on your side.
Common errors
| Symptom | Likely cause | Fix |
|---|---|---|
Signups not allowed for otp on login | First login for this email | Retry with harumi login --signup |
Provide --project or run from a directory with a .harumi binding | No project resolved | cd into a bound directory or pass --project <id> |
No Harumi project found in this directory (or any parent) on run | Directory isn't bound | harumi new/harumi clone <PROJECT_ID> to fetch one, or harumi link --project <PROJECT_ID> if the code is already here |
Not a Harumi repo / git remote errors | The harumi remote isn't configured | Re-run harumi link --project <PROJECT_ID>; ensure you're inside a git init-ialized directory |
No Gitea token found | Git token wasn't provisioned | Re-run harumi login |
Non-fast-forward / "fetch first" / "unrelated histories" on a manual git push harumi ... | Pushing normally against a repo that already has a scaffold commit | harumi clone <PROJECT_ID> first so you have the scaffold's history, then push from that clone. To create a new project from a folder, use harumi import (force-pushes intentionally, see Starting a project) |
Ran harumi new <NAME> --no-clone, but there's no folder for it | --no-clone only creates the project — it never touches the local filesystem | Run harumi clone <PROJECT_ID> (the id it printed) to fetch the code, or leave out --no-clone next time to create and clone in one step |
Run ended with status: failed on run --watch | Your code raised or exited non-zero | harumi runs get <RUN_ID> for the captured stdout/stderr/error |
You belong to multiple organizations | Org not set | harumi org use <ORG_ID> or pass --org per command |
A new project is missing from projects list, or landed in the wrong workspace | An older CLI ignored the configured organization when creating projects, so they went to your personal workspace | Upgrade the CLI (pipx upgrade harumi), or pass --customer-id <ORG_ID> explicitly. Already-created projects don't move on their own — change their workspace in the web app |
Not a directory: <path> on import | Pointed import at a file (e.g. a .zip) instead of a folder | Point it at an unzipped directory, or omit the path to import the current directory |
zsh: command not found: pip | Homebrew's Python only ships pip3, not pip | Use pipx install harumi (recommended), or pip3 install harumi / python3 -m pip install harumi |
error: externally-managed-environment on pip install | PEP 668 blocks pip outside a virtualenv | Use pipx install harumi, or add --user, or install into a venv |
Resetting local state
If your session or config gets into a bad state, they're plain files under
~/.harumi (or $HARUMI_HOME if set):
harumi logout # clears your stored sessionThe per-project binding lives separately in <project>/.harumi/config.json;
delete it to unbind a directory.