This topic helps you interpret and troubleshoot errors that might occur when using Cloud External Key Manager (Cloud EKM).
Structure of an error
The structure of the error messages provides as much granularity as possible to
help you diagnose and troubleshoot the problem. Errors are
returned in a google.rpc.Status
structure. Within that structure:
- The
google.rpc.Status.code
field shows the broad category of the error. - The
google.rpc.Status.message
field shows a human-readable message, including details about the specific action that was attempted and context-dependent suggestions for troubleshooting the error. If the
google.rpc.Status.code
isFAILED_PRECONDITION
, thegoogle.rpc.PreconditionFailure
structure is machine-readable. It contains twoviolation
structures.violation[0]
contains information about the state of the Cloud EKM key.violation[1]
contains information about the attempt to contact the external key management partner system.The
violation[1].type
contains information about the type of error. Cloud EKM refers to this information as the "error domain".If these errors persist, contact support for the external key management partner.
In this reference, the messages in the google.rpc.Status.message
are
truncated for readability. The truncated portion includes information such as
the external key URI.
Troubleshooting
Errors that occur when using Cloud EKM may be caused by problems with your inputs, Cloud EKM, the external key management partner system, communications between them, or other factors. You can read specific troubleshooting information in the section for each type of error.
Depending on the type of error, you may need to contact Cloud EKM support or support for the external key management partner system.
Input errors
Follow the troubleshooting advice in the google.rpc.Status.message
field of
the error. Check the external key URI or other inputs. If the
problem persists, contact Google Cloud support.
Unless otherwise noted, the errors in this section have google.rpc.Status.code
of
FAILED_PRECONDITION
.
google.rpc.Status.message |
violation[1].type (Error domain) |
Troubleshooting |
---|---|---|
Permission was denied when trying to access key URI. |
EXTERNAL_PERMISSION_DENIED |
If you encounter this error, Cloud EKM also disables the key version. Grant the appropriate permissions in your external key manager, and then try again by rotating the Cloud EKM key. |
Could not find resource at key URI. |
EXTERNAL_NOT_FOUND |
Check that the external key URI is correct. If it is, contact support for the external key management partner system. |
Key URI has invalid format. |
EXTERNAL_KEY_URI_INVALID |
Check that the key URI in this request is correct and try again by rotating the Cloud EKM key. |
Key URI host is not supported. |
EXTERNAL_KEY_HOST_NOT_WHITELISTED |
Check that the key URI is correct. If you are operating your own deployment of the external key management partner system, contact Google Cloud support. Otherwise, contact support for the external key management partner system. |
Could not resolve the domain name for key URI. |
DNS |
Check that the key URI is correct. If it is, contact support for the external key management partner system. |
Retriable errors
Follow the troubleshooting advice in the google.rpc.Status.message
field of
the error. If you observe frequent timeouts or network errors, ensure that the
geographic location of your Cloud EKM keys as near as possible to
the region you use for the external keys. If the problem persists, contact
support for the external key management partner.
Unless otherwise noted, the errors in this section have google.rpc.Status.code
of
FAILED_PRECONDITION
.
google.rpc.Status.message |
violation[1].type (Error domain) |
---|---|
Got throttled when trying to access key URI. |
EXTERNAL_RESOURCE_EXHAUSTED |
Could not reach key URI due to an external networking error. |
UNREACHABLE_NETWORK |
Could not reach key because the external key manager is slow or overloaded. |
OVERLOADED_EKM |
Timed out when trying to access key URI. |
TIMEOUT |
This error typically happens when the EKM is too slow to respond. Slowness can be caused by the EKM receiving more requests than it can handle or by network latency that is too high. |
REQUEST_CANCELLED |
External key management system errors
If you encounter these errors and they persist, contact support for the external key management partner.
Unless otherwise noted, the errors in this section have google.rpc.Status.code
of
FAILED_PRECONDITION
.
google.rpc.Status.message |
violation[1].type (Error domain) |
---|---|
Externally hosted CryptoKeys are not available to this caller. |
Empty |
Error in validating TLS server certificate for key URI. |
TLS_CERT |
Got garbled or unusable response when trying to access key URI. |
UNEXPECTED_RESPONSE |
Got external server error when trying to access key URI. |
EXTERNAL_SERVER_ERROR |
Got unimplemented error when trying to access key URI. |
EXTERNAL_NOT_IMPLEMENTED |
Got unexpected error when trying to access key URI. |
UNEXPECTED_ERROR |
Decryption failed: The EKM reports that decryption failed. If this error occurs, the key URI is valid, but the external key management partner system reports bad ciphertext or additional authenticated data (AAD). google.rpc.Status.code is INVALID_ARGUMENT . |
DECRYPTION_FAILED |
Getting support
If you experience an error not listed in this reference, contact Google Cloud support.