Skip to main content
Start with the health check. It reports authentication, API reachability, and version independently, so one failure does not mask another.

​
Authentication

Cause: no credentials are stored.Fix: sign in. See Authentication.
Cause: two or more workspaces are signed in, so the CLI cannot pick one for you.Fix: pass --subdomain on the command, or sign out of the ones you do not need.
Cause: --subdomain names a workspace you are not signed in to.Fix: run neetoinvoice whoami to see the signed-in accounts, then use one of those names or sign in to the new one.
Cause: login could not reach a NeetoInvoice workspace at that subdomain.Fix: pass only the part before .neetoinvoice.com. For acme.neetoinvoice.com the subdomain is acme. See workspace subdomain.
Cause: the sign-in was not approved in the browser within two minutes. The related message Authentication session expired. Please try again. means the server closed the sign-in session first.Fix: run neetoinvoice login again. If no browser opens, visit the URL the command prints.
Cause: the stored session is no longer valid. The CLI adds Suggestion: Authentication session expired. Run 'neetoinvoice login' to re-authenticate.Fix: sign in again for that subdomain.

​
Commands and flags

Cause: a required flag was omitted.Fix: check the flag table for that command in the command reference, or read the catalog directly with neetoinvoice commands.
Cause: team-members update was run with no change flags.Fix: pass at least one of the listed flags.
Cause: the server rejected the request body. The message names the failing field and the CLI adds Suggestion: Check required fields with 'neetoinvoice <command> --help'.Fix: correct the value and retry.
Cause: the installed binary predates it.Fix: upgrade, then refresh completion.
Cause: the completion script on disk was generated by an older binary.Fix: re-run the completion install for your shell and start a new shell. See Shell completion.
Cause: setup claude runs only on a machine where Claude Code has been started at least once.Fix: install and open Claude Code, then re-run neetoinvoice setup claude. See AI assistants.

​
Permissions

The CLI acts as the signed-in user, not as the workspace, so commands are limited by what your role allows. A request that a workspace API key would satisfy can still be refused for your account.
Cause: your role does not grant that permission. Viewing other users’ time entries, managing monthly PTO, and overriding autolock are each gated separately. The CLI adds Suggestion: You do not have permission to perform this action.Fix: ask a workspace admin to adjust your role, or run the equivalent REST API call with a workspace API key.
Cause: the ID or identifier does not exist in this workspace, or points at a record your role cannot see. The CLI adds Suggestion: Resource not found. Check the ID and try again.Fix: look the record up again with the matching list or show command. Clients and projects take their identifier; recipients, project users, team members, tasks, and time entries take their record id.
Cause: the entry has been included on an invoice, and billed entries are immutable.Fix: nothing to change on the entry. Adjust the invoice instead.

​
Connectivity

Cause: the request never reached the server. The subdomain is wrong, the network is blocking the request, or NEETOINVOICE_BASE_URL points somewhere unreachable.Fix: confirm the workspace subdomain, and unset NEETOINVOICE_BASE_URL if you had pointed the CLI at a local or staging server.
Cause: doctor could not open a connection to the workspace, for the same reasons as above.Fix: run neetoinvoice doctor --subdomain <name> with the subdomain you expect, and check the Error: line it prints beneath the check.
Cause: the workspace hit the API rate limit. The CLI adds Suggestion: Rate limited. Wait and try again.Fix: pause, then retry. Slow down loops that page through large result sets.

​
Reading errors

Every command exits non-zero on failure and writes the error to standard error, so a pipeline reading --json or --quiet output sees an empty payload and the exit code. Errors raised by the API take this shape:
The first line carries the server’s own message, or the HTTP status text when the server sent none. Field errors follow one per line, and a suggestion is added for 401, 403, 404, 422, and 429 responses.

​
Still stuck?

Visit the help center, email support@neetoinvoice.com, or join the Neeto Community.