> This page is for version Latest (default).
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.8.0: https://docs.nvidia.com/nemo-helix/v0.8.0/llms.txt
> - 0.7.1: https://docs.nvidia.com/nemo-helix/v0.7.1/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo-helix/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo-helix/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo-helix/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo-helix/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo-helix/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo-helix/v0.3.0/llms.txt
> - 0.2.0: https://docs.nvidia.com/nemo-helix/v0.2.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server.

# Troubleshooting

Use this page to find the right auth troubleshooting guide. The linked pages own
the detailed steps so this page can stay short.

## First Checks

```bash
curl -s "${NHX_BASE_URL:-http://localhost:8080}/apis/auth/discovery"
nemo auth status
nemo auth token --decode
```

Use these to confirm whether auth is enabled, which context and credentials the
CLI is using, and whether token claims such as `iss`, `aud`, `email`, `scope`,
or `scp` match the deployment configuration.

## Symptom Map

| Symptom                                                                                                     | Start Here                                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nemo auth login` fails, device flow is unavailable, scopes are rejected, or token claims do not match      | [OIDC Setup](/documentation/access-control/authentication/oidc-setup), then your provider page under [Authentication](/documentation/access-control/authentication)                                                                                   |
| Client Secret Basic returns `invalid_client`, redirect mismatch, or the CLI unexpectedly starts device flow | [Confidential OIDC Client](/documentation/access-control/authentication/confidential-client#troubleshoot-login)                                                                                                                                       |
| `401 Unauthorized` on API calls                                                                             | [Using Authentication](/documentation/access-control/authentication/using-authentication) for login, token inspection, SDK, and curl usage                                                                                                            |
| `403 Forbidden` after login                                                                                 | [Managing Access](/documentation/access-control/authorization/managing-access) for workspace roles, and [API Scopes](/documentation/access-control/authorization/api-scopes) for token scope restrictions                                             |
| Workspace deletion fails with a conflict                                                                    | [Managing Access - Deleting Workspaces](/documentation/access-control/authorization/managing-access#deleting-workspaces)                                                                                                                              |
| Role changes do not take effect immediately                                                                 | [Authorization Concepts - Role Propagation Delay](/documentation/access-control/concepts#role-propagation-delay) and [Policy Engine - Bundle Caching](/documentation/access-control/authorization/policy-engine#bundle-caching-and-propagation-delay) |
| Gateway bearer-auth callout, trusted headers, or header stripping is not working                            | [Gateway Integration](/documentation/access-control/deployment/gateway-integration)                                                                                                                                                                   |
| HelixAdmin does not have expected access                                                                    | [Auth Configuration - Bootstrap Admin](/documentation/access-control/deployment#bootstrap-admin) and [Security Model](/documentation/access-control/security-model)                                                                                   |
| Production hardening or secret handling questions                                                           | [Production Hardening](/documentation/access-control/deployment/production-hardening)                                                                                                                                                                 |

## If You Are Still Stuck

* Check auth service, gateway, and PDP logs for the exact failed decision.
* Confirm the request is reaching the expected gateway or service URL.
* Compare token issuer, audience, email, groups, and scopes with the platform
  `auth` configuration.