Cloud EKM error reference

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 is FAILED_PRECONDITION, the google.rpc.PreconditionFailure structure is machine-readable. It contains two violation 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 it is, 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

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 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.