afv-library/skills/salesforce-webapp-feature-react-agentforce-conversation-client-embedded-agent/docs/troubleshooting.md

Troubleshooting

Common issues when using the Agentforce Conversation Client.

---

Chat widget does not appear

Cause: Missing or invalid agentId. The component will not render anything without a valid agent ID.

Solution:

1. Verify agentId is passed in agentforceClientConfig — it is required
2. Confirm the ID is correct (18-character Salesforce record ID, starts with 0Xx)
3. Check that the agent exists and is Active in Setup → Agents

Chat loads but shows "agent not available"

Cause: The agent exists but is not deployed or is inactive.

Solution:

1. In Setup → Agents, ensure the agent status is Active
2. Verify the agent is deployed to the correct channel

Authentication error on localhost

Cause: localhost:<PORT> is not in the org's trusted domains for inline frames.

Solution:

1. Go to Setup → Session Settings → Trusted Domains for Inline Frames
2. Add localhost:<PORT> (e.g. localhost:3000)
3. Restart the dev server

Chat fails to authenticate / blank iframe

Cause: "Require first party use of Salesforce cookies" is enabled in the org's session settings. This blocks the embedded client from establishing a session.

Solution:

1. Go to Setup → Session Settings
2. Find "Require first party use of Salesforce cookies"
3. Uncheck / disable this setting
4. Save and reload the app

Multiple chat widgets appear

Cause: AgentforceConversationClient is rendered in multiple places.

Solution: Render it once in the app layout, not on individual pages. The component uses a singleton pattern — only one instance should exist per window.