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 the error domain is EGRESS, the problem involves the connection between Google and the external key management partner system. Report persistent errors of this type to Google Cloud support.
  
  Other error domain values indicate a problem with the external key management partner itself. 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`

Google server errors

Google server errors indicate a problem with our systems.

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
`External key error: Could not reach key URI.`	`EGRESS`	There is a networking problem between Google Cloud and the external key management partner system. Try again later. If the problem persists, contact Google Cloud [support].

An unlisted error with any of the following combinations of characteristics also indicates a Google server error.

google.rpc.Status.code is FAILED_PRECONDITION and google.rpc.PreconditionFailure.violation[0].type is EGRESS.
google.rpc.PreconditionFailure.violation[1].type is anything other than FAILED_PRECONDITION or INVALID_ARGUMENT. For example, INTERNAL.

If these errors persist, contact Google Cloud support.

Getting support

If you experience an error not listed in this reference, contact Google Cloud support.