> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.neetoinvoice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common neetoinvoice errors and how to resolve them.

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

```bash theme={"system"}
neetoinvoice doctor
```

## Authentication

<AccordionGroup>
  <Accordion title="not logged in. Run 'neetoinvoice login' to authenticate">
    **Cause**: no credentials are stored.

    **Fix**: sign in. See [Authentication](/cli/authentication).

    ```bash theme={"system"}
    neetoinvoice login --subdomain acme
    ```
  </Accordion>

  <Accordion title="multiple subdomains logged in (acme, beta); specify --subdomain">
    **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.

    ```bash theme={"system"}
    neetoinvoice clients list --subdomain acme
    ```
  </Accordion>

  <Accordion title="not logged in to &#x22;foo&#x22;. Logged in subdomains: acme, beta">
    **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.
  </Accordion>
</AccordionGroup>

## Commands and flags

<AccordionGroup>
  <Accordion title="required flag(s) &#x22;...&#x22; not set">
    **Cause**: a required flag was omitted.

    **Fix**: check the flag table for that command in the
    [command reference](/cli-reference/overview), or read the catalog directly with
    `neetoinvoice commands`.
  </Accordion>

  <Accordion title="A command or flag is missing from the CLI">
    **Cause**: the installed binary predates it.

    **Fix**: upgrade, then refresh completion.

    ```bash theme={"system"}
    neetoinvoice update
    neetoinvoice completion zsh
    ```
  </Accordion>

  <Accordion title="Completion does not suggest a newly added command">
    **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](/cli-reference/utility#shell-completion).
  </Accordion>
</AccordionGroup>

## 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.

<AccordionGroup>
  <Accordion title="A command is refused even though the record exists">
    **Cause**: your role does not grant that permission. Viewing other users' time entries,
    managing monthly PTO, and overriding autolock are each gated separately.

    **Fix**: ask a workspace admin to adjust your role, or run the equivalent
    [REST API](/getting-started/introduction) call with a workspace API key.
  </Accordion>

  <Accordion title="Editing a time entry fails because it is already billed">
    **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.
  </Accordion>
</AccordionGroup>

## Connectivity

<AccordionGroup>
  <Accordion title="API connection: could not reach https://acme.neetoinvoice.com">
    **Cause**: the subdomain is wrong, the network is blocking the request, or
    `NEETOINVOICE_BASE_URL` points somewhere unreachable.

    **Fix**: confirm the [workspace subdomain](/getting-started/workspace-subdomain), and
    `unset NEETOINVOICE_BASE_URL` if you had pointed the CLI at a local or staging server.
  </Accordion>
</AccordionGroup>

## Reading errors

Every command exits non-zero on failure and writes a single line to standard error. Errors
raised by the API carry the server's own message; inspect the JSON envelope, or the `--quiet`
payload, for `error`, `errors`, or `notice` keys.

```bash theme={"system"}
neetoinvoice clients show 7c1f5e2a9b --json
```

## Still stuck?

Visit the [help center](https://help.neetoinvoice.com), email
[support@neetoinvoice.com](mailto:support@neetoinvoice.com), or join the
[Neeto Community](https://neeto.com/community).