> This page is for version 0.8.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt
> - 0.9: https://docs.nvidia.com/nemo-helix/v0.9/llms.txt
> - 0.8: https://docs.nvidia.com/nemo-helix/v0.8/llms.txt
> - 0.7: https://docs.nvidia.com/nemo-helix/v0.7/llms.txt
> - 0.6: https://docs.nvidia.com/nemo-helix/v0.6/llms.txt
> - 0.5: https://docs.nvidia.com/nemo-helix/v0.5/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](/nemo-helix/v0.8/documentation/access-control/authentication/oidc-setup), then your provider page under [Authentication](/nemo-helix/v0.8/documentation/access-control/authentication)                                                                                   |
| Client Secret Basic returns `invalid_client`, redirect mismatch, or the CLI unexpectedly starts device flow | [Confidential OIDC Client](/nemo-helix/v0.8/documentation/access-control/authentication/confidential-client#troubleshoot-login)                                                                                                                                       |
| `401 Unauthorized` on API calls                                                                             | [Using Authentication](/nemo-helix/v0.8/documentation/access-control/authentication/using-authentication) for login, token inspection, SDK, and curl usage                                                                                                            |
| `403 Forbidden` after login                                                                                 | [Managing Access](/nemo-helix/v0.8/documentation/access-control/authorization/managing-access) for workspace roles, and [API Scopes](/nemo-helix/v0.8/documentation/access-control/authorization/api-scopes) for token scope restrictions                                             |
| Workspace deletion fails with a conflict                                                                    | [Managing Access - Deleting Workspaces](/nemo-helix/v0.8/documentation/access-control/authorization/managing-access#deleting-workspaces)                                                                                                                              |
| Role changes do not take effect immediately                                                                 | [Authorization Concepts - Role Propagation Delay](/nemo-helix/v0.8/documentation/access-control/concepts#role-propagation-delay) and [Policy Engine - Bundle Caching](/nemo-helix/v0.8/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](/nemo-helix/v0.8/documentation/access-control/deployment/gateway-integration)                                                                                                                                                                   |
| HelixAdmin does not have expected access                                                                    | [Auth Configuration - Bootstrap Admin](/nemo-helix/v0.8/documentation/access-control/deployment#bootstrap-admin) and [Security Model](/nemo-helix/v0.8/documentation/access-control/security-model)                                                                                   |
| Production hardening or secret handling questions                                                           | [Production Hardening](/nemo-helix/v0.8/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.