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 or key path.

Troubleshooting

Errors that occur when using Cloud EKM may be caused by problems with input errors, 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.

If your error isn't listed in the tables below, see Troubleshoot EKM via VPC errors.

Input errors

Follow the troubleshooting advice in the google.rpc.Status.message field of the error. 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 accessing the EKM_ELEMENT.`	`EXTERNAL_PERMISSION_DENIED`	When `EKM_ELEMENT` is `key`, 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. When `EKM_ELEMENT` is `crypto space` or `EKM host`, grant the appropriate role or permissions to the service account, and then try again.
`Could not find a EKM_ELEMENT` or `Could not query EKM host.`	`EXTERNAL_NOT_FOUND`	When `EKM_ELEMENT` is `key`, check that the external key URI or the key path is correct. When `EKM_ELEMENT` is `crypto space`, check that the crypto space path is correct. When an `EKM host` cannot be queried, check that the EKM hostname is correct. If they are spelled correctly, 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 EKM_ELEMENT.`	`DNS`	Check that the key URI, key path, crypto space, or EKM hostname 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. EKM_ELEMENT can be one of these value: key, crypto space, or EKM host.

`google.rpc.Status.message`	`violation[1].type` (Error domain)
`Throttled when trying to access key URI.`	`EXTERNAL_RESOURCE_EXHAUSTED`
`Could not reach the EKM_ELEMENT due to an external networking error.`	`UNREACHABLE_NETWORK`
`Could not reach the EKM_ELEMENT because the external key manager reports that it is overloaded.`	`OVERLOADED_EKM`
`Timed out when trying to access the EKM_ELEMENT.`	`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.