Skip to main content
Version: 1.1

Errors in Ratify

Ratify can generate various errors, either from its core workflow or from external/internal plugins. To facilitate easier debugging, Ratify will throw an error with a code property in most cases. This code can be used to identify the error and provide a more meaningful error message.

Error Codes

Errors from core workflow

System errors

CodeDescriptionTrouble Shooting Guide
EXECUTOR_FAILUREexecutor failureGeneric error returned when the executor fails to perform an operation.
BAD_REQUESTbad requestThe request is invalid or malformed. Check the request body and headers for more details.
AUTH_DENIEDauth deniedThe authentication to required resource is denied. Please validate the credentials or configuration and check the detailed error. For auth configuration in oras store, please refer to oras-auth-provider.
GET_CLUSTER_RESOURCE_FAILUREget cluster resource failureRatify failed to get required resources from the cluster. Please validate if the resources exists in the cluster and the access is correctly assigned.
DATA_DECODING_FAILUREdata decoding failureFailed to decode data. Please verify the decoding data.
DATA_ENCODING_FAILUREdata encoding failureFailed to encode data. Please verify the encoding data.

Configuration errors

CodeDescriptionTrouble Shooting Guide
REFERENCE_INVALIDreference invalidRatify failed to parse the given reference. Please verify the reference is in the correct format following docker convention: https://docs.docker.com/engine/reference/commandline/images/
CACHE_NOT_SETcache not setThe cache is not set successfully, please validate cache was created successfully during Ratify initialization.
CONFIG_INVALIDconfig invalidThe config is invalid. Please validate your config.
ENV_NOT_SETenv not setThe required environment is not set. Please set it up properly.
HOST_NAME_INVALIDhost name invalidThe registry hostname of given image or artifact is invalid. Please verify the registry hostname to ensure it can be correctly parsed
NO_MATCHING_CREDENTIALno matching credentialPlease verify the credentials is set up in K8s Secret. Please refer to oras-auth-provider for more details.

Errors from external/built-in plugins

Generic plugin errors

CodeDescriptionTrouble Shooting Guide
PLUGIN_INIT_FAILUREplugin init failureThe plugin fails to be initialized. Please check error details and validate the plugin config is correctly provided.
PLUGIN_NOT_FOUNDplugin not foundNo plugin was found. Verify the required plugin is supported by Ratify and check the plugin name is entered correctly.
DOWNLOAD_PLUGIN_FAILUREdownload plugin failureFailed to download plugin. Please verify the provided plugin configuration is correct and check the error details for further investigation. Refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/dynamic-plugins.md for more information.
CERT_INVALIDcert invalidThe certificate is invalid. Please verify the provided inline certificates or certificates fetched from key vault are in valid format. Refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/crds/certificate-stores.md for more information.
PROVIDER_NOT_FOUNDprovider not foundNo provider was found. Please verify that the necessary policy provider has been registered and that the provider's name has been entered correctly.

Verifier errors

CodeDescriptionTrouble Shooting Guide
VERIFY_REFERENCE_FAILUREverify reference failureGeneric error returned when the verifier fails to verify the reference. Please check the error details for more information.
VERIFY_PLUGIN_FAILUREverify plugin failureVerifier plugin failed to verify. Please check the error details from the verifier plugin and refer to plugin's documentation for more details.
SIGNATURE_NOT_FOUNDsignature not foundNo signature was found. Please validate the image has signatures attached.

Certificate Store errors

CodeDescriptionTrouble Shooting Guide
KEY_VAULT_OPERATION_FAILUREkey vault operation failedPlease validate correct key vault configuration is provided or check the error details for further investigation. Please review steps in ratify-on-azure for configuring Key Vault.

Referrer Store errors

CodeDescriptionTrouble Shooting Guide
LIST_REFERRERS_FAILURElist referrers failureReferrer store fails to list the referrers. Refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/store.md#listreferrers for more details.
GET_SUBJECT_DESCRIPTOR_FAILUREget subject descriptor failureReferrer store fails to get the subject descriptor. Refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/store.md#getsubjectdescriptor for more details.
GET_REFERRER_MANIFEST_FAILUREget reference manifest failureReferrer store fails to get the reference manifest. Refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/store.md#getreferencemanifest for more details.
GET_BLOB_CONTENT_FAILUREget blob content failureReferrer store fails to get the blob content.
REFERRER_STORE_FAILUREreferrer store failureReferrer store fails to get the blob content. Refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/store.md#getblobcontent for more details.
CREATE_REPOSITORY_FAILUREcreate repository failureFailed to create repository. Please verify the repository config is configured correctly and check error details for more information.
REPOSITORY_OPERATION_FAILURErepository operation failureThe operation to the repository failed. Please check the error details for more information.
MANIFEST_INVALIDmanifest invalidThe manifest is invalid. Please validate the manifest is correctly formatted.
REFERRERS_NOT_FOUNDreferrers not foundNo referrers are found. Please verify the subject has attached expected artifacts and refer to https://github.com/ratify-project/ratify/blob/main/docs/reference/store.md to investigate Referrer Store configuration.