Troubleshooting
Fixes for the most common problems with the desktop app, the command line, Git sync and coding agents.
Watch this in the tutorial: Troubleshooting (10:20)Start with the symptom in the table. Each row names the most likely cause and the fix. The two entries that have their own headings are behaviours that changed in 0.1.2, so they need a closer look.
Common problems
| Symptom | Fix |
|---|---|
The agent does not show getman as connected |
Check that getman is on your PATH, and that Node.js 20+ is installed. Start claude at the repository root. To see the error, run getman mcp --workspace getman by hand. |
401 with “Token request returned 401” |
A secret is empty. Set it in Environments, or export it for the command line and agents: export GETMAN_VAR_<KEY>=…. |
| Unknown environment (exit 3) | Use a name from the Environments list. |
| Requests skipped in production (exit 4) | This is intended. In the CLI, use --allow-mutations only when you mean it. For agents, approve the request when the agent’s client asks. |
| Pull is refused | Commit or discard your local changes first. A diverged branch needs a normal Git merge or rebase. |
| Push is disabled | The branch has no upstream. Run git push -u origin <branch> once. |
| Conflict markers or invalid YAML | Getman refuses to load the file. Fix it in Git, then run getman change validate --workspace getman. |
Two people created the same change ID, such as GT-…-007 |
In one file, change id: to the next free number, rename the file to match, and commit. |
| An assertion failed | The response Tests tab shows the expected and actual values. In the CLI, the run exits with 1 and prints the failing check. |
| “Couldn’t open that folder” | Pick the getman folder itself, the one that contains getman.yaml, not the repository root. |
| macOS says Getman can’t be opened | The build is not signed yet. Right-click Getman, choose Open, and confirm once. |
Saved secrets are locked (exit 5)
The command line and agents cannot read saved secrets until you allow it. When access is off, the CLI exits with code 5 and explains how to turn it on.
- Open Project settings → Command line & agents.
- Turn on Allow the command-line tool and agents to use saved secrets.
- Run the command again.
If you do not want to allow access, use --no-secrets and pass the values another way, such as GETMAN_VAR_<KEY>.
A request fails with “Status is not an HTTP error”
The server answered with a 4xx or 5xx status. Getman now treats that as a failure everywhere: in the app, the runner, the CLI and the agent tools. If the status is expected, add a status assertion for it, such as Status equals 401 on a request that tests the unauthorized case. Only an enabled status assertion can make an error status pass.
Known limits
- Production approval for agents depends on the client supporting the MCP confirmation form. It was tested with the MCP SDK client, not with Claude Code’s interactive interface.
- CI use of the command line has not been tested yet.
If your problem is not listed, check the command line reference for the exit code, and the MCP server page for agent problems. The handoff steps are in the team workflow.