---
title: "Troubleshoot an External Key Store"
description: "Troubleshoot External Key Store errors."
url: https://community.exoscale.com/product/security/kms/how-to/troubleshoot-external-key-store/
product: "Key Management Service (KMS)"
section: product
last_updated: 2026-10-22
---
> For AI agents: the documentation index is at https://community.exoscale.com/llms.txt. Every page is available as markdown at `<page URL>index.md` or with `Accept: text/markdown`.

# Troubleshoot an External Key Store

> [!IMPORTANT]
> **Private Preview**
>
> External Key Store (XKS) is currently available as a private preview. Review the [service boundaries](https://community.exoscale.com/product/security/kms/service-boundaries/index.md) for current limitations and SLA status.

An error on a key store, or on one of its KMS keys, comes from one of two places:

* **Exoscale KMS.** Before it calls your proxy, Exoscale KMS checks the key store and its keys: whether they exist in the zone, their state, their names and the request itself. These errors are listed in [Errors from Exoscale KMS](#errors-from-exoscale-kms).
* **Your XKS proxy or external key manager.** When a call to your proxy fails, Exoscale KMS returns `Key store proxy request failed`. If your proxy answered with an error, Exoscale KMS also passes that error on. These errors are listed in [Errors from your proxy](#errors-from-your-proxy).

For the results of the periodic health checks, see [Monitor the Health of a Key Store](https://community.exoscale.com/product/security/kms/how-to/operate-external-key-store/index.md#monitor-the-health-of-a-key-store).

## Errors from Exoscale KMS

| Error title | Cause | What to do |
| --- | --- | --- |
| `Key store not found` | No key store with this ID exists in the zone of the request. A key store belongs to a single zone. | Check the key store ID and the zone of the request. |
| `Key store is disconnected` | You used a KMS key in a disconnected key store, or tried to create one in it. | [Connect the key store](https://community.exoscale.com/product/security/kms/how-to/set-up-external-key-store/index.md#connect-and-disconnect-a-key-store), then retry. |
| `Key store is referenced` | You tried to delete a key store that still has KMS keys. | Delete the keys first and wait for their waiting period to end. |
| `Key store name already exists` | Another key store of your organization in this zone uses this name. | Choose a different name. |
| `Key store state changed` | The key store was modified by another request at the same time. | Retry the request. |
| `Invalid argument` | A field of the request is invalid, for example a proxy endpoint that is not an `https://` URL with a host, or a KMS key in an external key store requested with a usage other than `encrypt-decrypt`, a key spec other than `AES_256`, or as a multi-zone key. | Correct the field named in the error detail, then retry. |
| `Invalid origin` | You tried to replicate a KMS key in an external key store. These keys exist in a single zone. | Use the key in its own zone. |
| `Key store proxy request failed` | Exoscale KMS could not complete a call to your proxy: the proxy could not be reached, did not answer in time, or answered with an error. When you create a KMS key, it is also returned if the external key is disabled or does not allow both encryption and decryption. | Check the error detail. If your proxy answered with an error, see [Errors from your proxy](#errors-from-your-proxy). |
| `Invalid ciphertext` | The ciphertext cannot be decrypted with this KMS key. For a key in an external key store, it is also returned when your proxy reports `InvalidCiphertextException`. | Check that you decrypt with the KMS key and the encryption context used for encryption, and that the ciphertext is unchanged. |

## Errors from your proxy

When your proxy answers a request with an error, the error response of Exoscale KMS contains an `xks-proxy-error` object with two fields:

* `error-name`: the error your proxy returned, as defined by the [AWS KMS External Key Store Proxy API Specification](https://github.com/aws/aws-kms-xksproxy-api-spec/).
* `error-message`: the message your proxy returned, if any. It is written by your proxy and passed on unchanged.

The specification defines the following errors. Their cause is on your proxy or your external key manager.

| `error-name` | HTTP status | Meaning | What to check |
| --- | --- | --- | --- |
| `ValidationException` | 400 | The proxy considers a parameter of the request invalid. | That your proxy implements version 1 of the specification. |
| `InvalidStateException` | 400 | The external key or the key manager is disabled, deactivated or blocked. | The state of the external key in your key manager. |
| `InvalidCiphertextException` | 400 | Decryption only. The ciphertext, initialization vector, authentication tag or additional authenticated data is invalid. Exoscale KMS returns `Invalid ciphertext`. | That the ciphertext was produced by this KMS key and is unchanged. |
| `InvalidKeyUsageException` | 400 | The external key does not allow the requested encryption or decryption. | That the external key allows both encryption and decryption. |
| `AuthenticationFailedException` | 401 | The AWS SigV4 signature of the request is invalid. | The access key and secret key of the key store, and the region (the zone of the key store) and service name (`kms-xks-proxy`) configured in your proxy. |
| `AccessDeniedException` | 403 | The authorization rules of your proxy refused the request, based on its request metadata. | The rules of your proxy for the calling principal and the KMS key, described below. |
| `KeyNotFoundException` | 404 | The external key does not exist in your key manager. | The `external-key-id` of the KMS key. |
| `InvalidUriPathException` | 404 | The path of the request is not valid on your proxy. | The path of the key store endpoint, including its prefix, for example `/kms/xks/v1`. |
| `ThrottlingException` | 429 | Your proxy is limiting the rate of requests. | The rate limits of your proxy. |
| `InternalException` | 500 | Your proxy, or a component behind it such as your key manager, failed. | The logs of your proxy and of your key manager. |
| `UnsupportedOperationException` | 501 | Your proxy does not implement the operation, or a parameter exceeds the size it supports. | That your proxy implements `GetHealthStatus`, `GetKeyMetadata`, `Encrypt` and `Decrypt`. |
| `DependencyTimeoutException` | 503 | Your proxy timed out while reaching a component behind it, such as your key manager. | The connection between your proxy and your key manager. |

Requests to your proxy carry metadata that your proxy can use to authorize them, and that helps match its logs with your Exoscale requests:

| Field | Content | Sent with |
| --- | --- | --- |
| `awsPrincipalArn` | The ERN of the Exoscale API key or IAM user that made the request | `GetKeyMetadata`, `Encrypt` and `Decrypt` |
| `kmsKeyArn` | The ERN of the KMS key | `Encrypt` and `Decrypt` |
| `kmsOperation` | The Exoscale KMS operation, for example `Encrypt`, `Decrypt`, `GenerateDataKey`, `ReEncryptFrom`, `ReEncryptTo`, `CreateKey` or `KmsHealthCheck` | All requests |
| `kmsRequestId` | The ID of the Exoscale KMS request | All requests |