The most recent patch for this version is 26.2.1.  Learn more

Skip to main content
Version: 26.2

Troubleshooting

This page covers common ADS problems and how to fix them. Check the ADS startup log first: it contains detailed error messages that often identify the root cause.

ADS fails to start​

Symptom: The ADS process exits immediately or fails with an error during startup.

Common causes and fixes:

Missing or invalid license​

ADS requires a valid license file and will not start without one.

Check that:

  1. The license property in deployment.yaml points to the correct file path.
  2. The license file exists at that path and is readable by the ADS process.
  3. The license has not expired. ADS logs an expiration warning 30 days before expiry by default.

See Configure ADS for the supported path formats.

Invalid deployment.yaml​

If deployment.yaml contains a YAML syntax error, ADS fails to parse it at startup.

Check that:

  1. The file is valid YAML. Use a YAML linter to check for indentation errors, missing colons, or invalid characters.
  2. Any environment variable references use the correct syntax: ${VARIABLE_NAME:default_value}.
  3. Default values for environment variables in deployment.yaml do not contain hyphens (-), which is a Spring framework requirement.

Port already in use​

If another process is already listening on the configured port, ADS fails to bind at startup.

Check that:

  1. No other process is using port 8080 (or whichever port is configured in deployment.yaml).
  2. If you changed the port, the new value is set correctly under server.port in deployment.yaml.

Domain fails to load​

The behavior depends on when the failure occurs.

During startup​

ADS requires a valid domain to start. If the domain cannot be loaded, the service does not start.

If domain.startup.maxRetries is configured, ADS retries loading the domain up to that many times before giving up. Check the startup logs for the specific error.

Common causes:

  • domain.path in deployment.yaml points to a file that does not exist or is not readable.
  • The domain file contains a YAML syntax error.
  • A remote domain URL is unreachable at startup (for example, ADM is not yet available).

Fix:

  1. Confirm that domain.path points to an existing, readable file.
  2. Validate the domain YAML for syntax errors.
  3. If using a remote domain, confirm the URL is reachable from the ADS host. To handle temporary availability issues, configure startup retries. See Startup retry mechanism.

During a runtime update​

If domain.refreshInterval is configured and a domain reload fails, ADS continues running with the last successfully loaded domain.

To make ADS signal this condition through its health endpoint, set reportNotReadyOnDomainRefreshError: true. ADS then returns 503 Service Unavailable from its readiness probe until the domain is healthy again, removing the instance from rotation in Kubernetes or behind a load balancer.

See Healthcheck reporting on failed domain updates for configuration details.

Attribute connector errors​

Symptom: ADS returns HTTP 500 or Indeterminate decisions for requests that require external attributes. The response body may look like:

{
  "code": 500,
  "message": "Unable to get attribute Attributes.access_subject.subject_type"
}

Cause: The connector cannot reach its data source, or the data source returns unexpected data. When an attribute connector cannot connect to its Policy Information Point (PIP), ADS returns HTTP 500 Internal Server Error.

Fix:

  1. Check the connector configuration (host, port, credentials) in your domain YAML.
  2. Verify the data source is reachable from the ADS host or pod.
  3. Check ADS logs for the connector error details.

ADS includes the following standard attribute connectors: SQL, Table, LDAP, HTTP, and Parser. Each has its own connection properties to verify.

Authentication failures​

Symptom: ADS returns HTTP 401 or 403 for API calls that should succeed.

Common causes:

  • Wrong credentials in the request.
  • Token expired (for JWT/OAuth2 authentication).
  • OAuth2 misconfiguration, for example the jwk-set-uri is unreachable or the audiences value does not match the token's aud claim.
  • The request is missing the Authorization header entirely.
  • Legacy PBKDF2 password hash after upgrading to ADS 26.2.0: Hashes created with earlier ADS versions used an 8-byte salt (80 characters) instead of the 16-byte salt (96 characters) required by ADS 26.2.0.

Fix:

  1. Verify the credentials or token you are sending match what is configured in deployment.yaml.
  2. For JWT authentication, check that the jwk-set-uri is reachable from the ADS host and that the audiences property matches your token issuer's configuration. ADS caches JWKs for 5 minutes and refreshes them 30 seconds before expiry. If you recently rotated keys, wait for the cache to refresh.
  3. For basic authentication, confirm the username and password in deployment.yaml match what the client is sending.
  4. To temporarily disable authentication for testing purposes only, set authentication.enabled: false in deployment.yaml. Re-enable it before returning to production.
  5. For Basic authentication using {pbkdf2}, check the length of the hex string following {pbkdf2} in deployment.yaml. If it is 80 characters long, regenerate the hash (96 characters) or switch to {bcrypt}. See section PBKDF2 password hash compatibility on Migration guide.

See Configure authentication for configuration details.

TLS and certificate errors​

Symptom: Connections to ADS fail with SSL handshake errors. Or ADS cannot connect to an attribute connector or remote domain endpoint over TLS.

Common causes:

  • Certificate not trusted (the CA is not in the JVM truststore).
  • Certificate expired.
  • Hostname mismatch between the certificate and the connector host.

Fix:

  1. Add the CA certificate to the JVM truststore. For Kubernetes deployments, see JVM truststore. For JAR deployments, see Configure TLS.
  2. Check the certificate expiry date.
  3. Verify the hostname in the certificate matches the connector host you are connecting to.

Kubernetes deployment issues​

Symptom: The ADS pod fails to start, stays in CrashLoopBackOff, or fails readiness or liveness probes.

Common checks:

kubectl logs <ads-pod-name>
kubectl describe pod <ads-pod-name>

Common causes and fixes:

  • ConfigMap or Secret not mounted correctly: run kubectl describe pod <ads-pod-name> and check the Volumes and Mounts sections to confirm your deployment.yaml, license, and domain files are mounted at the expected paths.
  • Health probe paths misconfigured: ADS exposes three health probes: /health/liveness, /health/readiness, and /health/startup. Confirm these are set correctly in your Helm values.
  • Insufficient memory: ADS is a JVM application and requires adequate memory. Set appropriate resource limits in your Helm values. If the pod is OOMKilled, increase the memory limit.
  • Image pull failure: if the pod status is ImagePullBackOff, verify your registry credentials secret (regcred) is present and that the image path is correct.

See Deploy on Kubernetes for the full deployment procedure.

Performance and caching issues​

Symptom: Evaluation requests are slow. Cache hit rate is low.

Common checks:

  • Review the cache TTL settings in your domain YAML.
  • Check metrics for cache hit and miss rates.
  • For Kubernetes deployments with multiple pods, confirm that distributed caching is enabled with the -f ads/values-distributed-cache.yaml flag so all pods share cached attribute values.

Get help​

Contact Axiomatics Customer SupportOpens in a new tab for further assistance.