Troubleshoot Agentforce DX Issues

When building agents with Agentforce DX, you can run into errors at any stage of the workflow. Stages include generating authoring bundles, coding Agent Script files, publishing to your org, running agent tests, and deploying metadata. This topic collects the most common issues and their solutions.

Symptom: Some agent CLI commands fail with errors like This feature is not currently enabled for this user type or org or you can’t access Agentforce Builder in your org.

Solution:

In your org, go to Setup > Einstein Setup and turn on Einstein.
Go to Setup > Agentforce Agents and turn on Agentforce.

For scratch orgs, make sure that your scratch org definition file includes the Agentforce and Einstein features. For example:

See Set Up Your Development Environment for Agentforce DX.

The Agent Script .agent files are located in the aiAuthoringBundles/<api-name> directory of your DX project package directory, where <api-name> matches the API name of your agent’s authoring bundle.

Symptom: Running agent validate authoring-bundle (or the equivalent VS Code AFDX: Validate This Agent command) returns a syntax error with a line number.

Solution: Open the .agent file and go to the reported line. Common syntax mistakes include:

Missing or extra indentation — Agent Script uses indentation to define block scope (similar to YAML), so misaligned lines cause parse errors
Missing colons after block or property names (for example, config instead of config:)
Referencing a variable that hasn’t been declared in the variables block
Using an unsupported expression type

The Agentforce DX VS Code extension includes support for the Agent Script Language, so you see inline error highlighting as you type in a .agent file in the VS Code editor.

See the Agent Script documentation.

Symptom: Agent Script validation succeeds, but when you start a preview, the session fails to initialize.

Solution: Check that the config block in your .agent file includes a valid default_agent_user property set to an active agent user in your development org. This user is required for live mode and for Apex debug mode.

See Create the Default Agent User.

Symptom: The generated .agent file has little content, just boilerplate blocks with no subagents.

Solution: Pass an agent spec file with the --spec flag. Without a spec, the command generates a default template. The spec file gives the LLM the context that it requires to generate meaningful subagent definitions.

See Generate an Agent Spec File and Generate an Authoring Bundle.

Symptom: After running agent generate authoring-bundle with a spec file, the generated Agent Script file doesn’t accurately reflect your use case, or the subagents are too generic.

Cause: The quality of the generated authoring bundle depends on how specific and complete your agent spec file is. The LLM uses your spec as the primary input.

Solution: Refine your agent spec file with accurate, complete, and specific details about your agent’s purpose, the topics it can handle, and the actions available. Include:

Clear descriptions of what the agent can accomplish
Specific business processes or workflows the agent supports
Detailed descriptions of available actions and when to use them
Example user requests or scenarios the agent can handle

Then regenerate the authoring bundle with the improved spec.

See Generate an Agent Spec File and Generate an Authoring Bundle.

Symptom: You used agent create to create an agent, but there’s no associated Agent Script file. Also, some of the Agentforce DX commands don’t work with it.

Cause: The agent create command creates an agent that doesn’t use Agent Script as its blueprint. This older workflow is no longer the recommended approach.

Solution: Use the authoring bundle workflow instead:

Create an agent spec file describing your agent.
Generate an authoring bundle with agent generate authoring-bundle --spec <spec-file>.
Edit the generated .agent file.
Publish with agent publish authoring-bundle.

See Build an Agent with Agentforce DX for the complete workflow.

Symptom: You’re trying to package an agent template, but the command fails or doesn’t work for an agent created from an Agent Script file.

Cause: Agent template packaging currently doesn’t support agents that use Agent Script as their blueprint.

Solution: This issue is a known limitation. If you must package and distribute your agent, consider alternative distribution methods. Or check the latest Agentforce DX release notes for updates on this feature.

You publish an agent’s authoring bundle with either the agent publish authoring-bundle CLI command or the AFDX: Publish This Agent VS Code command.

Symptom: agent publish authoring-bundle completes without errors, but you can’t find the agent in your org.

Solution: Check these things:

Confirm you’re looking in the correct org. Run sf org display to verify your default org.
In Agentforce Builder, refresh the page. New agents aren’t always reflected immediately.

Symptom: You changed an Apex class or flow, published the authoring bundle, but the live preview still behaves as before.

Cause: Publishing an authoring bundle doesn’t deploy Apex classes or flows, which are separate metadata types.

Solution: Deploy your Apex and flow changes before publishing the authoring bundle.

Symptom: After running project retrieve start --metadata AiAuthoringBundle:My_Agent, only one version appears in your DX project.

Solution: Use the wildcard syntax to retrieve all versions.

Without the wildcard, the command retrieves only the unversioned (draft) bundle.

Symptom: project deploy start fails with an error about missing Bot or BotVersion components.

Cause: A committed agent requires both AiAuthoringBundle and Bot/BotVersion to deploy. If you’re deploying to a new org that doesn’t have the agent yet, you need both.

Solution: Use a manifest file that includes all the required metadata types. See Use Metadata to Move an Agent to a New Org and the manifest examples.

See Preview and Debug an Agent for details.

Symptom: You’re not sure whether to use --use-live-actions or --simulate-actions when starting a preview.

Solution: Choose based on what you’re testing:

Use --simulate-actions when your Apex classes, flows, or prompt templates aren’t yet available in your org, or when you want to test just the Agent Script logic without executing real actions.
Use --use-live-actions when you want to test the agent with actual Apex classes, flows, and prompt templates deployed to your development org. This mode is required to use the Apex Replay Debugger.

In VS Code, use the AFDX: Preview this Agent command and select either Simulation or Live Test from the drop-down in the Agent Preview tab.

Symptom: You’ve set breakpoints in your Apex code, but they aren’t hit during agent preview.

Solution: The Apex Replay Debugger only works in live mode. Make sure you’re using --use-live-actions when starting your preview session, and verify that Apex debug mode is enabled in your VS Code settings.

Simulated mode mocks all actions, so no actual Apex code executes.

Symptom: When using programmatic agent preview, you see an error about multiple active sessions when you try to send a message to an agent.

Solution: If you have multiple preview sessions for the same agent, specify which session to use with the --session-id flag. List all active sessions first.

To avoid confusion, stop unused sessions with sf agent preview stop --session-id <session-id>.

Symptom: Running agent test create returns an error that the agent doesn’t exist.

Cause: You must publish the agent to your org before you can create a test against it.

Solution: Publish the authoring bundle first.

Symptom: Tests pass when you run them manually with agent test run, but fail in your CI pipeline.

Solution: Check these common CI-specific issues:

Org authentication: Make sure that your CI environment is authorized to your development org using a JWT-based auth flow. Web login isn’t available in CI. See Set Up Your Development Environment for JWT setup.
Agent not activated: Some tests require the agent to be activated. Add an agent activate step before running tests in your CI script.
Async timing: If you’re using asynchronous test runs without --wait, poll for results with agent test resume --job-id <id> before evaluating pass/fail status. Note that exit code 1 means test cases had execution errors, not that assertions failed. Check the result output to distinguish the two.
Agent activation: Some tests require the agent to be activated. Add an agent activate step before running tests in your CI script.

Symptom: The test runs but metrics like coherence score below your threshold.

Solution: Low metric scores usually point to agent instructions or action descriptions that are too vague. Try these approaches:

Refine the system instructions in your Agent Script’s start_agent block.
Add more descriptive action descriptions in the relevant subagent definitions.
Use agent preview to have a freeform conversation and examine the trace output to understand where the agent’s reasoning diverges from your expectations.

See Customize the Agent Test Spec and Preview and Debug an Agent.