# Troubleshooting

## Check the installed version

```bash
npm ls @qentrah/auth-sdk
```

Compare the installed version with the version noted in this guide. Inspect your lockfile before changing dependencies; prerelease behavior may differ between versions.

## Import or module errors

Use only public import paths listed in [API and exports](/docs/npm-auth-sdk/reference). Avoid importing guessed paths inside `dist`. ESM-only packages require an ESM-aware application. Install declared peer dependencies in the consuming application.

## Error Handling

SDK errors are stable enough to branch on:

- `CONFIGURATION_ERROR`
- `AUTHORIZATION_DENIED`
- `INVALID_STATE`
- `TOKEN_EXCHANGE_FAILED`
- `ORGANIZATION_AUTHORIZATION_MISSING`
- `MISSING_RAW_BODY`
- `STALE_TIMESTAMP`
- `INVALID_SIGNATURE`
- `UNSUPPORTED_RUNTIME`

```ts
import { isQentrahPartnerAuthError } from "@qentrah/auth-sdk/partner";

try {
  await connectQentrah();
} catch (error) {
  if (isQentrahPartnerAuthError(error)) {
    await recordIntegrationIssue({
      code: error.code,
      message: error.message,
    });
  }
}
```

## Security Rules

Keep sensitive values out of browser code, public logs, screenshots, client bundles, docs, and version control.

- Browser code should only redirect to your backend start route.
- Exchange authorization codes on the server.
- Store access tokens, refresh tokens, client secrets, webhook signing secrets, and authorization codes in your own secure server storage.
- Verify webhook signatures before trusting event data.
- Render only sanitized credential and result snapshots in admin UI.
- Use placeholders in examples, docs, and tests.

## Callback failures

For `INVALID_STATE`, check that the same user session loads the saved pending state and that state is cleared after use. For token exchange failures, check the registered redirect URI, client configuration, and authority URL. Store refreshed tokens atomically and never send the stored token set to a browser.