Repository navigation
Troubleshooting
Failure modes visible in the source, with the text you will see. Errors go to
stderr prefixed Error:; the exit code is 1 except for argument-parsing
failures, which exit 2. Start with reportmateutil config, which shows what was
resolved and why a source was skipped.
Error: no API endpoint: set REPORTMATE_API_URL, or connect the ReportMate app on this machine (Settings → Connection)
No source supplied an endpoint: not the environment, the app's
connection.json, nor the runner's preferences. With REPORTMATE_NO_DISCOVERY
set, only the environment counts. See Configuration.
Error: no credential: set REPORTMATE_API_KEY (preferred), REPORTMATE_PASSPHRASE or REPORTMATE_TOKEN, connect the ReportMate app on this machine, or sign in to the deployment's cloud (az login / aws sso login)
Every source was tried and none gave a credential. Any step that was attempted and failed is listed under the message, for example:
Entra sign-in: az account get-access-token --resource api://example returned nothing (run az login)
Run az login (or aws sso login for an AWS deployment), or set a credential
in the environment.
The CLI reads the API key or passphrase the ReportMate app stored in the
Keychain. Allow it once. The prompt appears only when the app's connection uses
an API key or passphrase (or records no method) and no credential is set in the
environment. Setting REPORTMATE_API_KEY, REPORTMATE_TOKEN or
REPORTMATE_PASSPHRASE avoids the lookup; REPORTMATE_NO_DISCOVERY alone does
not.
The machine's own connection was picked up. Check the source line in
reportmateutil config, then either set REPORTMATE_API_URL and a credential,
or set REPORTMATE_NO_DISCOVERY=1 so only the environment is read.
Error: GET /api/v1/devices -> 401 Unauthorized: {"detail":"..."}
The credential is wrong, revoked, truncated or expired. Check that
REPORTMATE_API_KEY holds the complete rm_<id>_<secret> string. An API key in
the environment shadows every other source, so a stale one blocks a working
sign-in. A bearer token from az expires; re-run az login.
Error: PATCH /api/v1/device/SERIAL123/archive -> 403 Forbidden: {"detail":"This credential lacks the required 'admin' scope."}
The key is not admin-scoped. Anything under /admin, and every PUT, PATCH and
DELETE, needs admin. See Authentication.
These calls are restricted to internal-service callers; no API-key scope is
enough. Set REPORTMATE_INTERNAL_SECRET for the command, then unset it — the CLI
sends it on every request.
Error: GET /api/v1/hardwear -> 404 Not Found: {"detail":"Not Found"}
The CLI does not validate module names, tool names or raw paths. Check the spelling against the API's OpenAPI document.
The API bounds most numeric flags (for example devices --limit 1–1000,
module --limit 1–5000, admin usage-history cleanup --months 1–36) and the
CLI does not check them locally. The ranges are listed on Commands.
Error: --param must be key=value, got: limit
Every --param needs =. Only the first = splits, and both halves are
URL-encoded.
Error: path must start with /, e.g. /api/v1/dashboard
raw takes a path, not a URL; the base URL comes from the resolved endpoint.
device SERIAL --module NAME is shorthand for device SERIAL module NAME. Use
one form.
Error: refusing to delete SERIAL123 without --confirm
A local guard, checked before any request. The deletion is permanent and there is no prompt.
A command that expects JSON got text back, usually an HTML error page from a
proxy or a wrong base URL. Check the endpoint in reportmateutil config.
The tables show only string values; anything else renders as -, and an
unexpected response shape renders no rows. Re-run with --output json.
The HTTP timeout is 600 seconds, with no retry. Page large requests with
--limit and --offset.
The build uses rustls with a bundled root store and does not consult the OS
trust store; there is no --insecure or CA option. Serve the API with a
publicly trusted certificate.
In the top-level --help list, health has no description and config shows
health's line ahead of its own. Both commands behave as documented on
Commands; only the help text is crossed.
A locally built binary. Release builds stamp the calendar version from the tag
through RM_VERSION. See Development.
AGPL-3.0-or-later — reportmate.app