Agentforce agent errors — Agent Script compile and lint errors, sf agent validate, preview, publish and activate failures, the named-user JWT and scope errors, exit codes, and how the CLI talks to Salesforce
What a failing Agentforce DX step means and how to fix it — Agent Script diagnostics verbatim from Salesforce's linter (unsupported nested if, bad linked source, deprecated default_agent_user, invalid target scheme), CLI messages from validate, preview, publish and activate with their exit codes, the ApiAccessError and InvalidJwtToken errors when your own app lacks chatbot_api, sfap_api and web, the live-preview agent-user error, and the endpoints and timeouts underneath.
markdownreferencev1Q4FG-2108stage: buildtrust: officialservice: agentforceinterface: cliinterface: agent-scriptCompilation of the Agent Script file failedAgent Script compilation failedunsupported-nested-ifAgentScript does not support nested 'if' statementsconstraint-allowed-namespaces'source' must reference one of @MessagingSession @MessagingEndUser @VoiceCalldeprecated-field default_agent_user moved from config to accessconfig-missing-default-agent-user'default_agent_user' is required for AgentforceServiceAgentinvalid-action-target unsupported target schemeinvalid-procedure-value Expected procedure (->) or template (|) syntaxidentifier-confusable-booleanunsupported-operatorundefined-referencelinked-variable-cannot-have-defaultlinked-variable-cannot-be-listconnection-missing-required-fields messaging connections require at least one configuration fieldNo start_agent block foundCouldn't find a .bundle-meta.xml file with API nameWhen using --authoring-bundle you must specify either --use-live-actions or --simulate-actionsMultiple preview sessions found for this agentPreview session is invalid or has expiredAgent not found in the orgFailed to activate agentUnable to retrieve newly created Agent metadataUnable to deploy AiAuthoringBundle metadataError obtaining API tokenApiAccessErrorInvalidJwtToken Failed to create valid JWT for SFAP accesschatbot_api sfap_api web scopesensure the 'default_agent_user' set is validThis feature is not currently enabled for this user type or orgagentUser must be the username of an existing userexit codesagentforce/bootstrap/nameduserSF_AGENT_PUBLISH_METADATA_POLL_TIMEOUT_MINUTES
Agentforce agent errors
Where errors surface: the linter in your editor or work/tools/aslint.mjs (offline); sf agent validate authoring-bundle (server compile); sf agent preview and publish (compile, then org checks); sf agent activate. Add --json for the structured error and its actions.
Agent Script diagnostics (verbatim)
| Diagnostic | Fix | ||
|---|---|---|---|
| "AgentScript does not support nested 'if' statements. Combine conditions with 'and'/'or', or restructure the logic." | Flatten: if @variables.a and @variables.b: | ||
| "'source' must reference one of: @MessagingSession, @MessagingEndUser, @VoiceCall. Got @session" | A linked variable's source: use @MessagingSession.Id and similar. @session.sessionID and @messagingSession appear in Salesforce's recipes but fail | ||
| "'default_agent_user' is deprecated: Property default_agent_user has moved from config to access. Move field to access block." (warning) | Move it under access: | ||
| "'default_agent_user' is required for AgentforceServiceAgent type agents." | Add access: default_agent_user: "<agent user's username>" | ||
| "Action '…' uses unsupported target scheme "…://". Supported schemes: …" | Use a listed scheme (reference/agentforce/agent-script-actions-and-targets.md) | ||
| "Expected procedure (->) or template (\ | ) syntax, got '"…"'" | Reasoning instructions need -> or `\ | `, not a quoted string |
| "'true' is not a valid value in AgentScript. Did you mean 'True' (capitalized)?" | True, False, None | ||
| "Operator '*' is not supported" | Only + and -; compute in the action | ||
| "'transition' is not a defined value. Bare identifiers are not allowed here…" | In reasoning.actions write @utils.transition to @subagent.x | ||
| "'mian' is not defined in subagent" | A misspelt @subagent. name | ||
| "'@actions' cannot be used as a reference. This namespace is scoped to its parent block…" | run @actions.x where x isn't declared in this subagent's actions: | ||
| "Context variable '…' cannot have a default value." / "…cannot be a list." | Linked variables: no default, no list or object | ||
| "messaging connections require at least one configuration field (e.g. description)." | Fill connection messaging or remove it | ||
| "Invalid value "Queue" for …outbound_route_type" | outbound_route_type: "OmniChannelFlow" | ||
| "Invalid string: must match pattern /^A-Za-z*$/ for config" | developer_name: letters and digits, single underscores, no trailing underscore | ||
| "No start_agent block found" | Add start_agent agent_router: | ||
| "'topic' is deprecated: Replace topic with subagent." (warning) | Rename the block |
CLI messages
| Message | Cause → fix |
|---|---|
| "Compilation of the Agent Script file failed with the following errors: …" (validate, exit 1) / "Agent Script compilation failed. See errors above for details." (preview) | Fix the listed diagnostics. Exit 3 means the compile API returned HTTP 500: retry |
| "Couldn't find a ".bundle-meta.xml" file with API name '…' in the DX project." | --api-name is the bundle's folder name under aiAuthoringBundles/. Run from inside the project |
| "When using --authoring-bundle, you must specify either --use-live-actions or --simulate-actions." | sf agent preview start needs a mode for local bundles |
| "Multiple preview sessions found for this agent. Use the --session-id flag…" / "Preview session '…' is invalid or has expired." | Pass --session-id, or start a new one. sf agent preview sessions lists them |
| "Agent '…' not found. Check that the API name is correct and that the agent exists in your org or project." | --api-name works only for agents that are published and active. Publish and activate first, or use --authoring-bundle |
| "Agent '…' not found in the org." (activate, exit 2) / "Failed to activate agent: …" (exit 4) | Publish first. Exit 4 is an API or network error |
| "Unable to retrieve newly created Agent metadata. Due to: …" | The agent was published but the retrieve failed: sf project retrieve start --metadata "Bot:<Name>" (or AiAgentDefinition:<Name> at API 68+) |
| "Unable to deploy AiAuthoringBundle metadata. Due to: …" | The last publish step failed: deploy the bundle with sf project deploy start |
| "ensure the 'default_agent_user' set, is valid, and has the required permission sets assigned ['AgentforceServiceAgentBase', 'AgentforceServiceAgentUser', 'EinsteinGPTPromptTemplateUser']" | Live preview hit an internal error. Recreate the user with sf org create agent-user, or assign the three permission sets |
| "agentUser must be the username of an existing user in the org. Found: […]" | agent generate agent-spec --agent-user takes a username |
| "This feature is not currently enabled for this user type or org" | Turn on Einstein and Agentforce (guides/agentforce/build-agent-with-agentforce-dx.md, step 1) |
| "Error obtaining API token" (ApiAccessError) / "Failed to create valid JWT for SFAP access" (InvalidJwtToken) | Your login's app lacks the agent scopes: below |
Publish-time failures
From Salesforce's agentforce-generate skill. Validate only compiles. Publish is where the agent user's licence and every action target are checked, so a validated agent can still fail to publish.
| Symptom | Cause → fix |
|---|---|
| "Internal Error, try again later" | default_agent_user isn't an active user with the Einstein Agent licence. A System Administrator fails too. Find one: sf data query --query "SELECT Username FROM User WHERE Profile.UserLicense.Name = 'Einstein Agent' AND IsActive = true LIMIT 5" --target-org dev |
| "unknown error" on publish or preview of an employee agent | It sets default_agent_user. Remove the access block, because employee agents run as the signed-in user |
| "Duplicate value found: GenAiPluginDefinition" | start_agent and a subagent share a name |
| "Required fields missing: [BundleType]" | Extra fields in <Name>.bundle-meta.xml. Keep only <bundleType>AGENT</bundleType> |
| "Flow not found" | Deploy flows (and Apex, prompt templates) before publishing |
A new default_agent_user is rejected | Change it only while no version is active: deactivate, republish, reactivate |
Routing changes don't appear after sf project deploy start | Deploying the bundle doesn't update reasoning.actions. Publish it |
How the CLI talks to Salesforce
From @salesforce/agents, the library behind sf agent. Knowing this explains most auth failures:
- Compile (validate and preview):
POST https://api.salesforce.com/einstein/ai-agent/v1.1/authoring/scripts. Publish:POST .../v1.1/authoring/agents, or.../agents/<botId>/versionswhen the agent exists. - These calls need a named-user JWT, not a session ID. The CLI exchanges your session at
<instance>/agentforce/bootstrap/nameduser. If you logged in through your own connected app or ECA, it must grantchatbot_api,sfap_apiandweb. Otherwise the CLI fails with "Error obtaining API token". The web scope is easy to miss, because the Agent API's own setup doesn't list it (family 5). - Publish waits up to 10 minutes for the retrieve and deploy. Raise this with
SF_AGENT_PUBLISH_METADATA_POLL_TIMEOUT_MINUTES. - During publish the CLI adds a
<target>Steward_Agent.v1</target>to the bundle's meta file, deploys, then removes it. The hub's reading: a leftovertargetline means a publish was interrupted. - Preview sessions are cached under
.sfdx/agents/<agent>/sessions/<sessionId>/.