Troubleshooting

This topic groups common Delinea Credentials Cache problems by symptom. Start with Where to Find Logs, because almost every diagnosis depends on one of those log sources.

Where to Find Logs

Logs can be obtained from several layers:

Credentials Cache application log — written to the LogPath directory when EnableLogging is true (see Configuring Delinea Credentials Cache). Includes cache operations, secret fetch events, and errors. On Docker, this is the host directory mounted to /app/logs.
Hosting logs — Windows: Event Viewer > Windows Logs > Application (IIS and ASP.NET Core Module errors). Linux: sudo journalctl -u credcache.service for the application process, plus the Apache HTTP Server error log (/var/log/apache2/error.log on Ubuntu, /var/log/httpd/error_log on RHEL). Docker: docker logs delinea-credential-cache.
Distributed Engine logs — capture PowerShell script execution and pipeline-trigger activity for event-driven refresh.
Event Pipeline activity — in Secret Server or the Delinea Platform, Admin > Settings > Event Pipelines > Activity shows trigger execution status and failures.
Secret Server / Delinea Platform logs — record secret access, API calls, and authentication events.

Swagger UI Does Not Load

Platform	Likely cause	What to check
Windows (IIS)	Application pool stopped, IIS binding or physical path mismatch, ASP.NET Core Hosting Bundle missing or wrong version, or IIS_IUSRS lacks permission on the application folder	Confirm the application pool is Started and uses No Managed Code; review Event Viewer > Application; confirm the ASP.NET Core 10.0 Hosting Bundle is installed and run `iisreset`; re-check folder permissions from Installing Delinea Credentials Cache on Windows
Linux (Apache HTTP Server)	The `credcache` service is not running, the proxy points at the wrong local port, proxy modules not enabled, or SELinux blocks the proxy connection	Run `sudo systemctl status credcache.service` and `sudo journalctl -u credcache.service`; compare the port in `ProxyPass` with the port the service reports it is listening on; check the Apache error log; on RHEL run `sudo setsebool -P httpd_can_network_connect 1` if you see 503 errors
Docker	Container not running or wrong host port	Run `docker ps -a --filter "name=delinea-credential-cache"` and `docker logs delinea-credential-cache`; use the host port from the `-p` mapping (for example 8083 or 8443), not the container port

Container Problems

Symptom	Cause	Solution
Port already in use	Another application or container occupies the host port	Change the host port, for example `-p 9090:8080`
Container exits immediately	Startup failure inside the container	Check the logs: `docker logs delinea-credential-cache`
HTTPS does not work	Incorrect certificate password or file path	Verify that the `.pfx` file exists in the mounted directory and that `ASPNETCORE_Kestrel__Certificates__Default__Password` matches
Certificate not found	Missing or incorrect volume mount	Confirm the host path contains the certificate files and that the `-v` mount paths are correct
Secret Server connection untrusted	Mounted `.crt` not activated in the container's trust store	Run `docker exec delinea-credential-cache update-ca-certificates`, then retry; see Deploying Delinea Credentials Cache as a Docker Container
`<none>` image tag	The image loaded without a tag	Re-tag the image: `docker tag <image-id> delinea-credential-cache:<version>`

Token Request Fails or Credential Returns an Error

401 or 403 from /api/token — the vault rejected the credentials. Confirm the username, password, and BaseUrl (include /SecretServer for an on-premise installation), and that the account is not locked or MFA-enforced.
401 from /api/credential/{id} or /api/secretchanged — the Bearer token is missing, expired, or was issued to a different user. Request a new token and authorize again. Since v2.2.0, cache entries are keyed per user and token expiry is anchored to the vault token, so a token from one account cannot read another account's cached entries.
403 or 404 from /api/credential/{id} — the account does not have View permission on the secret (or on one of its parent folders), or the Secret ID does not exist.
TLS or certificate errors when the cache calls the vault — the host or container does not trust the vault's certificate. On Windows and Linux, import the vault's CA certificate into the OS trust store; on Docker, mount the certificate and run update-ca-certificates.

Application Receives an Old Password

If a secret was rotated less than CredCacheExpirationInMinutes ago (10 minutes by default) and event-driven refresh is not configured, the cache returning the previous value is expected behavior. Options:

Reduce the TTL (see Configuring Delinea Credentials Cache).
Configure Event-Driven Secret Refresh so the cache is updated immediately after each password change.
Restart the service to clear the cache (a last resort; the first request for every secret is then served from the vault).

Cache Is Not Updated After a Password Change (Event-Driven Refresh)

Work through the following checks in order.

Did the pipeline run? In Secret Server or the Delinea Platform, navigate to Admin > Settings > Event Pipelines, select the Activity tab, and locate the execution. Verify the Status (should be Success), Triggered by, and Timestamp. If there is no entry, the secret is not covered by the policy: check the trigger (Secret Password Change) and any secret filters. If a pipeline task fails, subsequent tasks in the same pipeline do not run.
Is the Distributed Engine healthy? Confirm that the Distributed Engine in the selected Run Site is running and online, and review its logs for the script execution.
Did the script fail silently? If the script ran but the token request failed with an empty password, the setting Event Pipelines: Allow Confidential Secret Fields to be used in Scripts is probably still False. Enable it as described in Prerequisites.
Can the Distributed Engine reach the cache? From the Distributed Engine host, open the Swagger URL stored in the CREDCACHEURL field. Confirm the URL includes the application alias or proxy path and no trailing slash, and that firewalls allow the port. If the cache uses a self-signed certificate, the script's ServerCertificateValidationCallback line bypasses validation in test environments only; in production, install the certificate on the Distributed Engine host.
Did the cache receive the call? Open the Credentials Cache log (the LogPath directory) and look for "Successfully retrieved the credential for [SecretID]", "Updating cache", and "Saving credential cache to file". If there are no entries at all, verify that EnableLogging is true. If the endpoint returned an error, check the token and permissions as described in Token Request Fails.
Is more than one instance deployed? Each instance must be notified separately. Confirm that a Run script task (or a secret with the matching CREDCACHEURL) exists for every instance.

One Credentials Cache Instance Is Unavailable

If a Credentials Cache instance becomes unavailable, other instances continue to operate normally and there is no impact on overall secret availability. When the unavailable instance comes back online, it retrieves secrets during the next update trigger or on the next on-demand request.

Recommendations:

Always deploy at least two Credentials Cache instances to avoid single-instance unavailability.
Use Event Pipelines to trigger secret updates consistently across all instances.
Ensure that each instance independently retrieves and caches secrets from Secret Server or the Delinea Platform; there is no dependency between instances. See Architecture.

For additional monitoring guidance, see Event Pipelines in the Secret Server documentation.