Mobb CLI Troubleshooting Guide
This guide describes how to troubleshoot common issues with the Mobb CLI.
Distribution differences
@mobb.ai/cli and mobbdev are the same CLI at the same version, but a few things behave differently because the binary has no Node.js runtime and no node_modules. You can mix the two distributions freely — they read the same access token and target the same Mobb tenant.
Commands that only work in the npm package
Two commands appear in --help (the command list is shared between distributions) but refuse to run in the binary. Run these with npx mobbdev@latest instead.
Command
Error in @mobb.ai/cli
scan --scanner checkmarx
The Checkmarx scanner is not available in the standalone mobbdev binary yet. Use the npm package instead: npx mobbdev@latest
claude-code-install-hook
Claude Code hooks are not available in the standalone mobbdev binary (they need a Node.js runtime). Install them with the npm package instead: npx mobbdev@latest claude-code-install-hook
The Checkmarx CLI is installed by the npm package's postinstall step, which never runs for a binary. The Claude Code hooks need a Node.js runtime to execute.
Platforms without a binary
Binaries are published for Linux x64/arm64, macOS arm64/x64, and Windows x64. Windows on arm64 has no binary. On any unsupported platform, use npx mobbdev@latest.
Installation Issues
Could not find the mobbdev binary package "@mobb.ai/cli-<os>-<arch>"
@mobb.ai/cli is a small launcher that resolves the prebuilt binary for your platform. That binary arrives as an npm optional dependency, so this error means the right platform package is not on disk.
Common causes and fixes:
Optional dependencies were skipped. Installs run with
npm install --no-optional,--omit=optional, or a lockfile/CI cache produced that way will not fetch the binary. Reinstall with optional dependencies enabled.Your platform has no binary. Windows on arm64 is not covered. See supported platforms.
In either case the Node.js package is the fallback — same CLI, same commands:
PowerShell fails with "The splatting operator '@' cannot be used..."
PowerShell treats a bare @ as the splatting operator, so an unquoted package name fails to parse before the command runs. Quote it:
bash, sh, and cmd.exe need no quoting.
Network and Connection Issues
WebSocket Connection Failures
By default, the Mobb CLI uses WebSockets to receive real-time updates about the analysis status. In some network environments—such as those behind strict corporate proxies, firewalls, or VPNs—long-lived WebSocket connections may be blocked or terminated unexpectedly.
Symptoms:
The CLI appears to hang or "spin" indefinitely during the analysis phase without updating.
You receive timeout errors waiting for the analysis to complete.
WebSocket connection errors appear in the debug logs.
Solution: Use Polling Mode
The Mobb CLI provides a --polling flag that forces the CLI to use HTTP polling instead of WebSockets. This method checks the analysis state every 5 seconds via standard HTTP requests and is generally more friendly to proxies and firewalls.
How to use:
Append the --polling flag to your analyze, review, or scan commands:
Verifying the Mode:
You can confirm which connection mode is being used by checking the console output or logs:
WebSocket Mode (Default):
Polling Mode:
Technical Details:
Polling Interval: 5 seconds
Timeout: 30 minutes
A run sits on "Waiting for analysis completion" and never returns
The last line you see is:
In WebSocket mode the CLI waits for a completion event with no client-side timeout, so if that event never arrives the command waits indefinitely rather than failing. This is most likely on runs that end in a source-control write — --auto-pr, --commit-directly, and review — because those depend on Mobb having a working SCM integration for the repository.
What to do:
Re-run with
--polling. Polling has a 30-minute timeout, so the command fails with a diagnosable error instead of hanging forever. This is the fastest way to turn a hang into a message.Confirm the repository's SCM token is registered with Mobb — via the Integrations page or
add-scm-token. Fixes cannot be pushed without it.Confirm automatic PR is enabled for the project under Project Settings → Fix Policy, as described in Automatic PR.
--auto-prrespects that policy, so a run can complete the analysis and still produce no PR.Open the report URL the CLI printed. The scan and fix generation happen before the SCM step, so the report is usually there even when the write step does not finish — which tells you the analysis succeeded and the problem is downstream.
Proxy environments
Set HTTPS_PROXY (or HTTP_PROXY) before invoking the CLI. Both https:// and http:// URLs are accepted in HTTPS_PROXY. See HTTPS_PROXY settings.
Authentication Issues
The CLI keeps asking me to log in, or uses the wrong tenant
The access token is cached per Mobb API host, in a file named mobbdev-<API_HOST>.json under ~/.config/configstore/ (C:\Users\<USERNAME>\.config\configstore\ on Windows). If you switch between the multi-tenant cloud and a single-tenant instance, each gets its own file, and a token written for one host is not used for the other.
Confirm
API_URLpoints at the tenant you expect. The default ishttps://api.mobb.ai/v1/graphql, whose token file ismobbdev-api_mobb_ai.json.To force a fresh login, delete the matching
mobbdev-<API_HOST>.jsonfile.See Location of the Mobb Access Token for the exact naming rule.
Argument Validation Errors
The CLI rejects invalid flag combinations before doing any work. The most common ones:
--ci flag requires --api-key to be provided as well
Add --api-key when running non-interactively
--gate enforces the policy on a Mobb scan and cannot be combined with --scan-file
Drop -f / --scan-file, or drop --gate
--commit-directly flag requires --auto-pr to be provided as well
Add --auto-pr
--create-one-pr flag requires --auto-pr to be provided as well
Add --auto-pr
--create-one-pr and --commit-directly cannot be provided at the same time
Pick one
--pull-request flag requires --commit-directly to be provided as well
Add --commit-directly
Missing required argument: repo
-r / --repo is mandatory on analyze, scan, and review
Missing required arguments: ch, commit-hash
Add --ch / --commit-hash — see Review Mode
--gate judges Mobb's own scan, so it cannot be combined with --scan-file — a third-party report carries no Mobb rule identities for the policy to judge.
For Snyk scans, --scanner snyk also requires a SNYK_TOKEN environment variable in --ci mode. See Scan Mode.
Scan and Fix Errors
Digesting report failed on a run with no scan file
A Scan and Fix run (no -f / --scan-file) that ends with:
is reporting a report-format problem for a run that had no report file. The usual cause is a --baseline-commit SHA that is not reachable from the repository being scanned. The run fails with exit code 1, and the failure can take a while to surface.
Confirm the SHA resolves in the repository you are scanning:
Convert-to-SARIF Errors
convert-to-sarif prints nothing on success. These are the failures it can return:
Error: --input-file-path flag should point to an existing file
The input path does not exist
Error: Bad archive
The input file is not a ZIP archive (an FPR is a ZIP)
Error: the input file should be in a valid Fortify FPR format.
The archive has no audit.fvdl entry
Invalid values: Argument: input-file-format
--input-file-format must be FortifyFPR
Other Files You May See
Alongside the token file, the config directory can contain mobbdev-<API_HOST>-session-<uuid>.json files. These are per-session working files used by the Claude Code integration, not token stores, and are pruned automatically.
Debug Logs
To get verbose output for any of the above, set DEBUG=* before the command. See Debug Mode.
Last updated