Skip to main content

​
Overview

This guide covers platform-level Key Manager issues that require administrator access. For user-facing issues such as 403 errors or expired secrets, see the Key Manager Troubleshooting guide.
Administrator Access Required — This operation requires the admin role. Contact your Polystack administrator if you do not have sufficient permissions.

​
Diagnostic Checklist

Check Key Manager container status
Verify Key Manager API is responding
Check Key Manager API logs

​
Platform Issues

Secret retrieval returns 500 Internal Server Error

Cause: The secret store backend is unavailable — HSM connectivity lost, KMIP server unreachable, or master key file inaccessible.Diagnosis:
Check Key Manager worker logs for backend errors
Resolution by backend type:
Cause: The CA plugin is unreachable or misconfigured.Diagnosis:
Check order status and error detail
Review the error_status_code and error_reason fields. Common causes:
  • CA plugin service is not running — check container status via the deployment console
  • Certificate subject DN contains invalid characters or fields rejected by the CA
  • CA connectivity timeout — verify network access from Key Manager to the CA endpoint
Check CA plugin container
Cause: ACL changes require a short propagation delay, or the caller is authenticated under a different user identity than expected.Diagnosis:
Verify ACL on the secret
Confirm the user ID in the ACL matches the authenticated user’s actual ID:
Get current user ID
Resolution: If the user ID does not match, ensure the correct user identity is being used in the API call. ACL entries reference user IDs, not usernames — a renamed user retains the same ID.
Cause: Database connectivity failure, missing master key file, or configuration error preventing service initialization.Diagnosis:
Check startup logs
Common startup failures:
Cause: The secret store backend is under load or the encryption operation is slow (common with PKCS#11 HSM under high request rates).Resolution:
  • Check HSM health and current load from the HSM management interface
  • Consider scaling Key Manager worker replicas via the deployment console to parallelize requests
  • For KMIP backends, verify network latency to the KMIP server
  • Review Key Manager worker logs for timeout or retry events

​
Log Locations

​
Next Steps

Key Manager Troubleshooting (User)

User-facing Key Manager issues — 403 errors, expired secrets, ACL problems

Backend Configuration

Verify and update secret store backend configuration

Architecture

Understand component roles to narrow down failure scope

Security

Security hardening to prevent recurrence