Troubleshooting

Troubleshooting

Diagnose and resolve common DuoKey AWS XKS Proxy issues

Applies to:

AWS XKS ProxyConnectivity IssuesError Resolution

Quick Diagnostic Checklist

Prerequisites

• External key store connection status verified
• XKS proxy health endpoint responding
• Network connectivity from AWS to proxy confirmed
• TLS certificates valid and not expired
• SigV4 authentication credentials correct
• External key exists in key manager
• External key manager accessible from proxy
• Recent CloudWatch metrics showing activity
• Proxy logs showing recent requests

Common Issues

1. XksProxyUriUnreachableException

Warning

Error:XksProxyUriUnreachableException: The XKS proxy URI endpoint is unreachable

Possible Causes:

• XKS proxy is down or not running
• Network connectivity issues
• Firewall blocking AWS KMS IP ranges
• DNS resolution failure
• TLS certificate issues

Diagnose ConnectivityBASH

# 1. Check the XKS endpoint is responding
curl -k https://your-proxy-address.com/health

# 2. Check DNS resolution
nslookup your-proxy-address.com
dig your-proxy-address.com

# 3. Check TLS certificate
echo | openssl s_client -connect your-proxy-address.com:443 -servername your-proxy-address.com

# 4. Review recent request activity for this endpoint in DuoKey Cockpit,
#    or in your own log aggregation platform if you forward Cockpit's output there

Note

The XKS proxy is served by the same DuoKey Cockpit process as your other apps — there is no separate proxy binary or service to restart independently. If you self-host Cockpit, "restarting the proxy" means restarting your Cockpit deployment (which affects all apps, not just this endpoint); if DuoKey hosts Cockpit for you, contact support.

---

2. XksProxyInvalidResponseException

Warning

Error:XksProxyInvalidResponseException: The XKS proxy returned an invalid response

Possible Causes:

• Proxy not conforming to AWS XKS proxy API specification
• JSON formatting issues in proxy responses
• Incorrect HTTP status codes
• Missing required response fields

---

3. XksProxyIncorrectAuthenticationCredentialException

Warning

Error:XksProxyIncorrectAuthenticationCredentialException: Authentication credential is incorrect

Possible Causes:

• SigV4 credentials mismatch between AWS and proxy
• Credentials expired or rotated
• Clock skew between AWS and proxy

---

4. XksKeyNotFoundException

Warning

Error:XksKeyNotFoundException: External key not found

Possible Causes:

• Key ID mismatch (case-sensitive)
• Key deleted from the vault backing the endpoint
• The endpoint's configured vault or key no longer exists or is disabled

---

5. High Latency Issues

Symptoms: Operations taking more than 100ms to complete

Possible Causes:

• Network latency between AWS and proxy
• External key manager performance issues
• Proxy resource constraints
• Geographic distance

---

6. TLS Certificate Issues

Symptoms: TLS handshake failures or certificate warnings

Possible Causes:

• Expired certificates
• Certificate chain incomplete
• Wrong certificate for domain
• Certificate not trusted by AWS

---

7. External Key Store Disconnected

Symptoms: External key store shows as disconnected

Advanced Troubleshooting

Debug Mode

Note

There is no local proxy configuration file to toggle debug logging - the XKS proxy is served by your DuoKey Cockpit deployment. If standard diagnostics aren't enough, contact DuoKey Support: they can enable verbose server-side logging for your endpoint while you reproduce the issue.

Packet Capture

Capture Network TrafficBASH

# Capture HTTPS traffic to/from proxy
tcpdump -i any -s 0 -w /tmp/xks-traffic.pcap port 443

# Analyze with Wireshark
wireshark /tmp/xks-traffic.pcap

Health Check Debugging

Detailed Health CheckBASH

# Detailed health check
curl -v https://your-proxy/xks/<prefix>/kms/xks/v1/health \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

# Expected response (per the AWS XKS proxy API specification):
# {
# "xksProxyFleetSize": 1
# }

Error Code Reference

Error Code	Description	Common Causes
XksProxyUriUnreachableException	Cannot reach proxy	Network, firewall, proxy down
XksProxyInvalidResponseException	Invalid proxy response	API compliance, bugs
XksProxyIncorrectAuthenticationCredentialException	Auth failure	Wrong credentials, clock skew
XksKeyNotFoundException	External key not found	Wrong key ID, key deleted
XksKeyInvalidConfigurationException	Key config invalid	Wrong key type, key disabled
XksProxyInvalidConfigurationException	Proxy config invalid	Wrong URL, invalid settings

Getting Help

Before Contacting Support

Gather Diagnostic InformationBASH

# 1. Your XKS endpoint name/ID and, if you self-host DuoKey Cockpit,
#    your Cockpit deployment version

# 2. Recent request activity for the endpoint, exported from DuoKey Cockpit
#    or from wherever you've aggregated Cockpit's request logs

# 3. External key store status
aws kms describe-custom-key-stores \
  --custom-key-store-id cks-xxxxx > keystore-status.json

# 4. CloudWatch metrics
aws cloudwatch get-metric-statistics \
  --namespace AWS/KMS \
  --metric-name XksProxyLatency \
  --dimensions Name=CustomKeyStoreId,Value=cks-xxxxx \
  --start-time $(date -u -d '1 hour ago' '+%Y-%m-%dT%H:%M:%S') \
  --end-time $(date -u '+%Y-%m-%dT%H:%M:%S') \
  --period 300 \
  --statistics Average,Maximum > cloudwatch-metrics.json

# 5. Network test results
curl -v https://your-proxy:443/health > network-test.txt 2>&1

Contact Information

Resource	Contact
DuoKey Support	[email protected]
AWS Support	Open case in AWS Console
Community	GitHub Discussions

Preventive Measures

Regular Health Checks

Automated Health Check ScriptBASH

#!/bin/bash
# /usr/local/bin/xks-health-check.sh

PROXY_URL="https://your-proxy:443/health"
ALERT_EMAIL="[email protected]"

RESPONSE=$(curl -s -o /dev/null -w "%{http_code}" $PROXY_URL)

if [ "$RESPONSE" != "200" ]; then
  echo "XKS Proxy health check failed: HTTP $RESPONSE" | \
      mail -s "XKS Proxy Alert" $ALERT_EMAIL
  exit 1
fi

exit 0

Schedule Health CheckBASH

# Add to cron
*/5 * * * * /usr/local/bin/xks-health-check.sh

Regular Maintenance Schedule

Frequency	Task
Weekly	Review logs and metrics
Monthly	Test disaster recovery procedures
Quarterly	Rotate credentials
Annually	Renew TLS certificates

Next Steps

Key Management

Manage your KMS keys

Monitoring

Set up comprehensive monitoring

Getting Started

Return to setup guide

See Also

• Key Management
• Monitoring
• Getting Started