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

# Troubleshooting

> Diagnose authentication and connectivity issues with neetoengage doctor.

## Run the doctor

When something goes wrong, start with `neetoengage doctor`. It checks your authentication, API connection, and CLI version.

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

When multiple workspaces are signed in, name the one to check:

```bash theme={"system"}
neetoengage doctor --subdomain your-workspace
```

## Common errors

When a command fails, it prints an error message to standard error and exits with status 1. Usage errors such as an unknown flag or a missing argument add `Run 'neetoengage --help' for usage.`

<AccordionGroup>
  <Accordion title="Not authenticated. Run 'neetoengage login' to authenticate.">
    **Problem**: no workspace is signed in. <br />
    **Solution**: run [`neetoengage login --subdomain <name>`](/cli/authentication).
  </Accordion>

  <Accordion title="Multiple subdomains authenticated (acme, beta); specify --subdomain.">
    **Problem**: more than one workspace is signed in, so the target is ambiguous. <br />
    **Solution**: add `--subdomain <name>` to the command. For `logout`, `--all` signs out of every workspace.
  </Accordion>

  <Accordion title="Not authenticated for &#x22;foo&#x22;. Authenticated subdomains: acme, beta.">
    **Problem**: the `--subdomain` value does not match any signed-in workspace. <br />
    **Solution**: use one of the listed subdomains, or [sign in](/cli/authentication) to the new one.
  </Accordion>

  <Accordion title="Subdomain not found. Please check that you entered the correct subdomain.">
    **Problem**: `neetoengage login` could not find a workspace at `<subdomain>.neetoengage.com`. <br />
    **Solution**: use the first part of your workspace URL. For `https://spinkart.neetoengage.com`, enter `spinkart`.
  </Accordion>

  <Accordion title="Authentication session expired. Please try again.">
    **Problem**: the browser sign-in was not approved before the session expired. `NeetoEngage CLI authentication timed out after 5 minutes. Please try again.` means the CLI stopped waiting. <br />
    **Solution**: run `neetoengage login` again and approve the sign-in in the browser. If the browser does not open, visit the URL the CLI prints.
  </Accordion>

  <Accordion title="Could not connect to NeetoEngage. Check your internet connection">
    **Problem**: the CLI could not reach the API. <br />
    **Solution**: check your network and run `neetoengage doctor`. If [`NEETOENGAGE_BASE_URL`](/cli/authentication#environment-variables) is set, confirm it points at a reachable server.
  </Accordion>

  <Accordion title="required flag(s) &#x22;xxx&#x22; not set">
    **Problem**: a required flag was omitted. <br />
    **Solution**: check the command's [reference page](/cli-reference/overview) or run `neetoengage <command> --help` for the required flags.
  </Accordion>

  <Accordion title="API error (422): <message>">
    **Problem**: the server rejected the request. The CLI prints `API error (<status>): <message>`, one line per additional error, and a `Suggestion:` line for common statuses: 401 (sign in again), 403 (no permission), 404 (check the ID), 422 (check required fields with `--help`), and 429 (rate limited, wait and retry). <br />
    **Solution**: follow the suggestion. For 401, run `neetoengage login` to refresh the session.
  </Accordion>

  <Accordion title="Claude Code not found (~/.claude/ does not exist).">
    **Problem**: `neetoengage setup claude` requires Claude Code to have been run at least once. <br />
    **Solution**: install and open Claude Code, then run the command again.
  </Accordion>
</AccordionGroup>

## Known API responses

Some requests fail with a NeetoEngage-specific message:

| Situation | What you see |
| - | - |
| `feature-requests search` while the search server is down | `API error (503): search_unavailable`. Wait and retry. |
| An `<id>` that matches no feature request | `API error (404):`. Use the UUID or the slug at the end of the request's admin URL. |
| `settings update` with no flag | `pass --product-name, --website-url, or both` |
| A `--website-url` that does not start with `http://`, `https://` or `www.` | `API error (422):` with the validation message. |

## Check the version

```bash theme={"system"}
neetoengage version
```

Prints the CLI version, commit hash, and build date - useful when reporting an issue. To upgrade, run [`neetoengage update`](/cli-reference/utility#update).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.