This article provides an overview of common issues encountered with the "readMetadata" API in Salesforce and offers steps to troubleshoot and resolve them. The "readMetadata" API is used to retrieve metadata components, but errors can occur if the requested metadata is inaccessible or improperly configured. 


Common Causes of readMetadata Errors 

Below are some of the most common reasons why the "readMetadata" API may fail to retrieve the requested component: 

1. Incorrect metadata reference: 

  • The "fullName" provided in the API call does not match the actual metadata component's unique identifier. This could be due to a typo, incorrect namespace prefix, or using the wrong format. 

2. Metadata component does not exist: 

  • The requested metadata component has been deleted, renamed, or was never deployed in the Salesforce environment. 

3. Access restrictions: 

  • The user or API integration does not have sufficient permissions to access the metadata component. 

4. API restrictions in managed packages: 

  • Metadata components from some managed packages may be restricted and not exposed via the Salesforce API for security or proprietary reasons. 

5. Incomplete metadata deployment: 

  • The metadata may have been partially deployed or failed during deployment, leaving it inaccessible. 


Common Error Messages 

When using the "readMetadata" API, you may encounter the following errors: 

  • "Failed to get file: /Metadata/[Component Path]. Cause: readMetadata didn't return component with given fullName": 
    • This error occurs when the specified metadata component cannot be found. 
  • “UNKNOWN_EXCEPTION (targetObject is invalid)": 
    • This indicates that the metadata is referencing an invalid or inaccessible target object. 
  • "INVALID_TYPE_FOR_OPERATION (entity type does not support bulk id query)": 
    • This happens when the requested entity type does not support the operation being performed, such as a bulk query. In this case, we will try to download the records again with a different API.


How to Troubleshoot readMetadata Errors 

Follow these steps to resolve "readMetadata" errors: 


1. Verify metadata existence: 

  • Navigate to Setup > Object Manager, Custom Metadata Types, or Installed Packages, depending on the type of metadata being requested. 
  • Confirm that the requested metadata component exists and is correctly configured.

2. Check fullName format: 

  • Ensure the "fullName" in the API call matches the required format for the component type. For example: 
    • Custom metadata: "[ObjectAPIName]-[RecordName]"
    • Quick action: "[ObjectAPIName].[ActionName]"

3. Review permissions: 

  • Ensure the API user has the necessary permissions to access the metadata. This includes field-level security, profile permissions, and API access. 

4. Contact managed package provider: 

  • If the error involves a managed package, verify with the package provider whether the requested metadata or data is accessible via the API. 

5. Enable debug logs: 

  • Use Salesforce debug logs to capture detailed error information and identify the root cause of the issue. 

6. Redeploy or recreate metadata: 

  • If the metadata component is missing or corrupted, redeploy it using a deployment tool or recreate it directly in the Salesforce UI.

Best Practices for Using readMetadata 

  • Use Salesforce CLI or Workbench to validate metadata availability. 
  • Maintain up-to-date documentation of metadata components, including "fullName" formats and namespace details. 
  • Regularly review and clean up unused or outdated metadata to prevent referencing non-existent components. 
  • Work with managed package vendors to understand API limitations and ensure the necessary metadata is exposed for your use cases.

Additional Resources 

For further information on the "readMetadata" API and troubleshooting metadata issues, refer to: