Agentforce: How to Troubleshoot Common Agentforce Errors

1. Configuration Errors

Symptoms

• Agentforce agents do not execute configured workflows

• “Access Denied” or “Insufficient Privileges” errors appear

• AI actions are missing or cannot be executed in the UI

Common Causes

• Missing user or integration permissions

• Flow Orchestration or Einstein Copilot features not enabled

• Incorrect object-level access or sharing settings

Troubleshooting Steps

• Verify User Permissions
  Confirm the user profile or assigned permission sets include access to Agentforce features such as Manage Flows, Einstein Copilot, and View All Data.

• Confirm Feature Enablement
  Navigate to Setup → Feature Settings → Agentforce and ensure all required features are enabled.

• Review Object Permissions
  Validate CRUD and sharing permissions for all Salesforce objects used in the workflow.

• Run Flow Debugger
  Use Flow Debugger to identify the specific step or condition causing the failure.

Best Practice

Use a centralized permission set group for all Agentforce and AI-related users to ensure consistent access control.

2. Data Errors

Symptoms

• Agentforce responses are incomplete or irrelevant

• AI-generated insights appear inaccurate

• Automations fail due to missing required values

Common Causes

• Data Cloud sync delays or paused data streams

• Null, invalid, or outdated field values

• Inconsistent relationships between Salesforce records

Troubleshooting Steps

• Check Data Sync Status
  Navigate to Data Cloud → Data Streams and verify that all the source data streams are active and syncing successfully.

• Review Field Mappings
  Ensure correct mappings between source systems and Data Cloud data model objects.

• Validate Data Completeness
  Use SOQL queries or reports to identify missing, null, or stale records.

Best Practice

Implement Data Quality Rules and alerts to proactively detect and correct data issues.

3. Integration Errors

Symptoms

• Agentforce fails to invoke external systems (for example, AWS, Slack, or custom APIs)

• Errors such as 401 Unauthorized or 500 Internal Server Error

• Slow responses or timeout failures

Common Causes

• Expired OAuth tokens or invalid API keys

• Endpoint URL changes not reflected in Salesforce

• Missing or misconfigured Named Credentials

Troubleshooting Steps

• Validate Named Credentials
  Go to Setup → Security → Named Credentials and confirm credentials are active and correctly configured.

• Review API Logs
  Use Event Monitoring → API Usage Logs to identify failed calls and review HTTP status codes.

• Renew Authentication Tokens
  Refresh OAuth tokens or reauthorize connected apps as needed.

• Test API Connectivity Externally
  Use tools such as Postman to verify endpoint availability and behavior outside Salesforce.

Best Practice

Implement retry logic and monitoring alerts for integration failures within flows.

4. Runtime Errors

Symptoms

• Agentforce processes stop before completing

• Errors such as Unhandled Exception or Null Pointer Exception

• Unexpected automation loops or logic failures

Common Causes

• Incorrect flow logic or uninitialized variables

• Recursive triggers or circular dependencies

• Salesforce governor limits exceeded

Troubleshooting Steps

• Use Flow Debug Mode
  Step through execution paths to identify the failing node or variable.

• Review Apex Logs
  Inspect debug logs in Developer Console for stack traces and error details.

• Monitor Governor Limits
  Check limit usage for SOQL queries, DML operations, and CPU time.

• Simplify Flow Design
  Refactor complex flows into smaller, reusable subflows.

Best Practice

Always configure Fault Paths in flows to handle runtime exceptions gracefully.

5. AI Prompt Errors

Symptoms

• AI responses are inconsistent, irrelevant, or incomplete

• The agent misinterprets instructions or fails to act

• Identical inputs produce different outputs

Common Causes

• Ambiguous or poorly structured prompts

• Missing or invalid context data

• Excessively long prompts causing token constraints

Troubleshooting Steps

• Review Prompt Structure
  Ensure prompts clearly define the role, task, and context.

• Validate Dynamic Variables
  Confirm that all referenced variables (for example, {{Case.Subject}}) contain valid data.

• Test Prompt Variations
  Iterate on prompt wording and compare output consistency.

• Apply Einstein Trust Layer Controls
  Filter sensitive or unnecessary data before sending prompts to the LLM.

Best Practice

Document, standardize, and version-control prompts using Salesforce DevOps Center.

6. Agent Deployment Errors

Symptoms

• "We couldn't create a new version" when cloning agents

• Duplicate key value violations during agent deployment

• Error: "Required fields are missing: [PlannerId]"

• Agents not appearing after metadata deployment

• Version control issues between sandboxes and production

Common Causes

• Metadata dependencies not properly resolved

• Required fields not populated during deployment

• Duplicate agent names or API names

• Missing referenced components (flows, actions, objects)

• Insufficient permissions for deployment user

Troubleshooting Steps

• Validate metadata dependencies in the target org.

• Check required fields during agent deployment.

• Handle duplicate key value errors by reviewing existing agents.

• Follow deployment best practices using sandboxes and change sets.

• Test agent activation and functionality after deployment.

Best Practice

Maintain a deployment checklist with all prerequisites. Use DevOps Center or version control to track agent configurations and changes.

Advanced Troubleshooting Techniques

• Enable Agentforce debug logs under Setup → Monitoring → Debug Logs.

• Use Event Monitoring Analytics to track agent behavior and API calls.

• Run Salesforce Health Check to validate org readiness.

• Reproduce issues in a sandbox environment before applying fixes in production.

Common Error Codes