Agentforce: Common Deployment & Metadata Errors and How to Resolve Them

Category 1: Planner & Planner Bundle Errors

Error: Function not found: null

Metadata Type

GenAiPlannerBundle / GenAiPlanner

Error Message

GenAiPlannerBundle: <AgentName> — Function not found: null

Cause

The planner references a GenAiPlugin or GenAiFunction that does not exist in the target org or was not included in the deployment package.

Resolution

• Deploy all dependencies before deploying the Agent metadata.

• Recommended deployment order:

  1. Flows

  2. Apex Classes

  3. Custom Objects and Fields

  4. Prompt Templates

  5. GenAiPlannerBundle

  6. Bot and BotVersion

• Beginning with Winter '26, GenAiPlugin and GenAiFunction are bundled within GenAiPlannerBundle and should not be deployed as standalone metadata.

• Retrieve metadata using:

sf project retrieve start --metadata Agent:<AgentName>

Error: Required fields are missing: [Function]

Metadata Type

GenAiPlugin / GenAiPlanner

Error Message

GenAiPlugin: <Name> — Required fields are missing: [Function]

GenAiPlanner: <Name> — Function not found: null

Cause

The referenced function has not yet been deployed.

Resolution

Deploy all referenced actions and functions before deploying the planner.

Error: Required fields are missing: [PlannerId]

Metadata Type

BotVersion

Error Message

BotVersion: <AgentName>.v1 — Required fields are missing: [PlannerId]

Cause

The BotVersion references a GenAiPlannerBundle that is missing from the deployment package.

Resolution

• Always deploy GenAiPlannerBundle together with Bot and BotVersion.

• Prefer deploying using sf project deploy start --source-dir.

• Verify the deployment uses GenAiPlannerBundle instead of the legacy GenAiPlannerDefinition metadata type.

Error: Invalid variable or attribute reference

Metadata Type

GenAiPlanner

Error Message

GenAiPlanner: <AgentName> — Invalid variable or attribute reference: <VariableName>

Cause

Variable mappings referenced by the planner cannot be resolved during deployment.

Resolution

Temporarily remove variable mappings before deployment and recreate them after deployment.

Error: GenAiPlanner failed to deploy due to invalid cross reference id

Metadata Type

GenAiPlanner

Error Message

EmployeeCopilotPlanner of Type GenAiPlanner failed to deploy due to invalid cross reference id

Cause

Occurs when switching from Agentforce Default Agent to Employee Agent and deploying to a target org where the Default Agent has been disabled or the referenced BotVersion no longer exists.

Resolution

• Before deploying, verify target org BotVersion records: SELECT Id FROM BotVersion WHERE Id = '<referenced_id>'
  
  
• If Agentforce Default Agent is disabled in target, the cross-reference IDs from the source are invalid — recreate the planner referencing the correct agent in target

Error: InvocableTarget not found

Metadata Type

GenAiPlannerBundle

Error Message

InvocableTarget not found: <FlowName>

Cause

Local action (Flow or Apex) referenced in the GenAiPlannerBundle was not included in the deployment. Local actions must be deployed alongside or before the bundle.

Resolution

• Ensure all referenced Flow, Apex Class, Prompt Template, etc are included in the deployment package and deployed before GenAiPlannerBundle


•  Verify the Flow API name in the bundle XML matches exactly

Category 2: Metadata Retrieval Errors

Error: UNKNOWN_EXCEPTION during metadata retrieval

Error Message

UNKNOWN_EXCEPTION: An unexpected error occurred.

Cause

Backend metadata corruption prevents metadata retrieval.

Resolution

Contact Salesforce Support and provide the Error ID for metadata cleanup.

Error: API Version Mismatch

Metadata Type

GenAiPlannerDefinition

Error Message

An unexpected error occurred. Please include this ErrorId if you contact support: <ErrorId>
Metadata API Name: Agentforce | Type: Generative AI Planner Definition

Cause

The source and target orgs are using incompatible Metadata API versions.

Resolution

• Align the API versions across environments.

• Use API version 64.0 or 65.0 when appropriate.

Category 3: Metadata Structure Errors

Error: Entity of type 'GenAiFunction' or 'GenAiPlugin' cannot be found

Metadata Types

GenAiFunction / GenAiPlugin

Error Message

Entity of type 'GenAiFunction' named '<Name>' cannot be found.

Cause

Beginning with Winter '26, these metadata types are no longer deployed separately.

Resolution

• Remove GenAiFunction and GenAiPlugin from package.xml.

• Deploy GenAiPlannerBundle instead.

Error: Element isCompatibleAgent invalid

Metadata Type

BotVersion

Error Message

Element isCompatibleAgent invalid at this location in type BotVersion

Cause

The target org is running an earlier Salesforce release that does not support this field.

Resolution

• Wait for the target org to be upgraded to latest salesforce release.

• Remove unsupported fields before deployment if necessary.

Error: Duplicate key value violates unique constraint

Metadata Type

Agentforce Employee Agent

Error Message

Duplicate key value violates unique constraint

Cause

Duplicate backend records exist after Winter '26 metadata structure changes.

Resolution

• Delete the agent in the target org and re-deploy.
  
  
• Ensure only the latest agent version is deployed — clean up outdated versions in the Bots folder before deploying

Error: Required field is missing: entryDialog

Metadata Type

Bot

Error Message

Required field is missing: entryDialog

Cause

entryDialog is a mandatory field for certain Bot metadata schemas in 2GP managed packaging. Manually adding it to XML causes schema validation errors due to format mismatch.

Resolution

• Agentforce metadata is not fully supported in 2GP managed packages as of current releases. Contact Salesforce Support if deployment through managed packages is required.
  
  
• For unlocked packages, ensure the Bot XML schema matches the target API version exactly

Category 4: Permission & Provisioning Errors

Error: ValidationException.No_Data_Available

Error Message

ValidationException.No_Data_Available

Cause

Agentforce metadata provisioning is incomplete in the target org.

Resolution

• Toggle Agentforce OFF → ON: Setup > Agentforce Agents > toggle OFF, wait 5 mins, toggle ON
  
  
• Ensure Einstein is enabled, Einstein Bots feature is on, and Data Cloud Setup is complete
  
  
• Workaround 1: Create a dummy NGA bundle with a random script in target org → delete it → retry deployment
  
  
• Workaround 2: Remove agentScript directory from GenAiPlannerBundle change set and deploy via SFDX

Error: SFDC_PERMISSION_ERROR

Error Message

DataKitDeployPolling job executed successfully, but component is in error state: ''
permissionErrors: [GenAiFunctionDefinition, GenAiPluginDefinition]
errorCode: SFDC_PERMISSION_ERRORFDC_PERMISSION_ERROR

Cause

Agentforce or Einstein setup is incomplete.

Resolution

• Confirm Agentforce is enabled and and at least one agent exists in the org.

• Verify the Salesforce CRM connection in Data Cloud.

• Ensure Einstein/Generative AI settings are enabled.

Category 5: Data Cloud Deployment Errors

Error: sfm_AgentOpt deployment failed

Error Message

DataKitDeployPolling job executed successfully, but component is in error state: 'sfm_AgentOpt'

Cause

A Data Kit synchronization mismatch exists after sandbox refresh or metadata changes.

Resolution

• Reconnect the AgentOpt Connector: Data Cloud Setup → Ingestion API → AgentOpt → click Activate. Verify all 4 streams (AgentOpt-Tag, AgentOpt-Tag Def Association, AgentOpt-Tag Def, AgentOpt-Tag Association) transition from "Needs Activation" → Active
  
  
• Re-toggle Agentforce Session Tracing: Turn OFF → ON to trigger a fresh data kit deployment
  
  
• Contact Salesforce Support if the issue persists.

Category 6: Missing Backend Records

Error: Something went wrong, refresh in Agent Builder (missing backend SObject records)

Error Message

Something went wrong. Refresh.

Cause

GenAiPluginDefinition and GenAiFunctionDefinition SObject records are NOT being created during metadata deployment. The UI reads from GenAiPlannerBundle metadata (topics/actions appear fine), but session creation reads from Core SObject records — which are missing.

Diagnostic Query:

SELECT Id, DeveloperName FROM GenAiPluginDefinition
SELECT Id, DeveloperName FROM GenAiFunctionDefinition

If 0 records returned post-deployment, this is the issue.

Resolution

• Remove and re-add actions in Agentforce Builder UI to trigger SObject record recreation
  
  
• Redeploy using GenAiPlannerBundle at API v65 via Workbench or CLI
  
  
• If BotUserId is null in BotDefinition: redeploy the Bot record to repopulate the Agent User field

General Deployment Best Practices

• Correct metadata types (post-Winter '26 / API 65+):

Recommended deployment order:

• • Flows, Apex Classes, Custom Objects/Fields
  • Prompt Templates
  • GenAiPlannerBundle (includes topics & actions post-Winter '26)
  • Bot and BotVersion
  • Manually configure: Agent User, Data Library (cannot be deployed via metadata)
    
    
• Agent User field is not deployable via metadata — must be set manually in the target org after deployment
  
  
• Data Library creation is not deployable — must be set up manually post-deployment
• For NGA Deployment please refer to : Troubleshoot Agentforce DX Issues