--- cuppy_hub: salesforce cuppy_path: reference/agentforce/agent-errors.md cuppy_section: docs cuppy_doc: Q4FG-2108 cuppy_doc_uuid: 078e83a1-d4a3-4c7f-9e1e-c69744c6c260 cuppy_permalink: https://cuppy.io/salesforce/d/Q4FG-2108 cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/salesforce/docs/reference/agentforce/agent-errors cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 96a90a931018e391b918391e0e8cbd08a2d1cb1dd5d5962f0e88bed3c3a6be59 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # 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: ""` | | "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](_?[A-Za-z0-9])*$/ 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:"` (or `AiAgentDefinition:` 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 `.bundle-meta.xml`. Keep only `AGENT` | | "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//versions` when the agent exists. - These calls need a **named-user JWT**, not a session ID. The CLI exchanges your session at `/agentforce/bootstrap/nameduser`. If you logged in through your own connected app or ECA, it must grant **`chatbot_api`, `sfap_api` and `web`**. 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 `Steward_Agent.v1` to the bundle's meta file, deploys, then removes it. The hub's reading: a leftover `target` line means a publish was interrupted. - Preview sessions are cached under `.sfdx/agents//sessions//`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.