> For the complete documentation index, see [llms.txt](https://docs.pal.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pal.aic.io/engineering-and-delivery/troubleshooting.md).

# Troubleshooting

<details>

<summary>The container builds but the first operation says no token provider is registered</summary>

This is the fail-closed default. Register `IPalantirAccessTokenProvider` or configure the `Palantir:ClientCredentials` section so Foundation can add the Foundry OAuth2 adapter.

</details>

<details>

<summary>The first operation fails with a licence error</summary>

Check `PalantirOfflineLicenseOptions` or the configured online entitlement provider. Confirm the file is readable by the process, the signature key matches the AIC-issued licence, the product is `PAL.NET`, the validity window includes the current UTC time, and the enrollment host/operation is entitled. Do not fix this by disabling the licence guard.

</details>

<details>

<summary>Startup fails before the application starts</summary>

This usually means local configuration validation failed. Check:

* `BaseAddress` and `TokenEndpoint` are absolute HTTPS URIs;
* `ApiVersion` contains no slash;
* retry, timeout, response, and serialization limits are within range;
* encrypted settings have a valid 32-byte key;
* production supplies `ConnectionStrings:DefaultConnection` for Foundation repository startup.

Registration itself does not contact Palantir. A startup network call indicates host code or another dependency is performing work outside PAL.NET registration.

</details>

<details>

<summary>HTTP 401 or 403</summary>

401 is mapped to `Authentication`; 403 is mapped to `Authorisation`. Check token expiry, token audience, operation scopes, enrollment, and the upstream identity's permissions. A valid licence does not grant upstream access.

</details>

<details>

<summary>HTTP 429 or 5xx</summary>

Inspect `PalantirApiException.Classification`, `DiagnosticId`, and `RetriesExhausted`. Safe requests may already have been retried. Respect upstream `Retry-After`; do not add aggressive unbounded host retries. For mutations, verify idempotency before retrying.

</details>

<details>

<summary><code>PalantirResponseTooLargeException</code></summary>

The response exceeded `MaxBufferedResponseBytes`. Use the operation's streaming method or generated streaming contract. Do not raise the buffer limit without considering memory pressure and request concurrency.

</details>

<details>

<summary>Stream appears empty or socket usage grows</summary>

Make sure the response wrapper is disposed after copying or parsing the stream. Use `await using` for async consumers and avoid returning a stream after its owning wrapper has been disposed.

</details>

<details>

<summary>Pagination repeats or never completes</summary>

PAL.NET stops when it sees a repeated page token. Investigate the upstream response and preserve the page token for a reproducible support case. Do not write an application loop that ignores repeated tokens.

</details>

<details>

<summary>Generated operation is missing</summary>

Check the pinned compatibility source and visibility/stability classification. Regenerate models and bindings from the normalized source, review the gap report, and add a reviewed mapping or façade only when the operation is within the public release scope.

</details>

<details>

<summary>Configuration values do not override each other as expected</summary>

Apply the Foundation precedence order in [Configuration](/foundations/configuration.md). Environment variables use `__` separators, for example `Palantir__MaxRetries`. Confirm the active environment and the process base directory used to locate `PAL.{environment}.json` or `settings.{environment}.enc`.

</details>