Troubleshoot Custom LWC Rendering Issues in Agentforce

1. Verify the LWC is Exposed Correctly (Standard LWC)

Ensure the component is configured to be surfaced in the correct context.

• Check the component's *.js-meta.xml for valid <targets>:

<targets>
<target>lightning__AppPage</target>
<target>lightning__RecordPage</target>
<target>lightning__HomePage</target>
</targets>

• For Embedded Messaging / Experience Cloud, the target must include lightningCommunity__Page or lightningCommunity__Default.

• Agentforce custom actions using LWC require the component to be Screen Flow-compatible — ensure isExposed is true.

• For Custom Lightning Types (CLT), use the correct target type:

  • Input override LWC → lightning__AgentforceInput

  • Output renderer LWC → lightning__AgentforceOutput

2. Known limitation : CLT Renderer Doesn't Render in Draft Mode

The CLT output renderer card does not render in the Agentforce Builder preview panel if the agent is in Draft mode. You must commit and activate the agent first to test CLT rendering. This is a known platform limitation — not a misconfiguration.

3. Check for Locker Service / Lightning Web Security (LWS) Conflicts

Agentforce surfaces enforce Lightning Web Security (LWS), which may block certain JavaScript APIs that work in other contexts.

• Open Setup → Session Settings and confirm Lightning Web Security is enabled.

• Test the LWC in isolation using the Lightning Component Library.

• Common LWS violations:

  • Direct DOM manipulation (document.querySelector, window.* access)

  • Use of third-party scripts loaded via <script> tags

  • Cross-component CustomEvent dispatching with non-serializable payloads

Important: LWS errors may appear silently in the Agentforce panel but are visible in the browser console.

4. Validate Wire Adapters and Apex Calls

• Confirm that any @wire adapters used in the component are supported in the current API version.

• Ensure Apex methods invoked from the LWC are annotated with @AuraEnabled(cacheable=true) where applicable.

• Check that the running user has the required object/field permissions and Apex class access via Profile or Permission Set.

• For getRecord wire adapter — verify the fields list is accurate and the user has Field level security on all requested fields.

5. Inspect the Component in Builder Preview vs. Runtime

6. Fix Intermittent LWC Rendering via Topic Instruction Quality

Intermittent LWC failures (renders sometimes, blank other times) are often caused by ambiguous or poorly structured topic instructions.
Apply these best practices:
Structure instructions as explicit steps:

STEP 1 — EXTRACT: Extract required fields from user input.
STEP 2 — VALIDATE: Run the action ONLY IF all required fields are present.
STEP 3 — EXECUTE: Immediately run the action without additional questions.
STEP 4 — DISPLAY: ALWAYS include the returned LWC component in your response.
STEP 5 — FOLLOW-UP: After showing the component, optionally ask for additional details.

Avoid these patterns:

Key rule: In the action output instructions, explicitly add: "ALWAYS include the returned LWC component in your response, even if some fields are still being processed."

7. Review the Custom Action Configuration (Standard Actions)

If the LWC is used as part of an Agentforce Custom Action:

• Navigate to Agent Builder → Actions and confirm the action is correctly linked to the LWC.

• Ensure the action's input/output variables match the LWC's exposed @api properties.

• Validate that the Flow screen component wrapping the LWC does not have misconfigured variable mappings.

• Check the Action Invocation Logs in Setup → Agentforce → Logs for runtime errors.

8. Clear Cache and Test in Incognito

Browser-cached metadata can cause stale rendering:

1. Open an Incognito / Private window

2. Navigate to the Agentforce surface

3. Check if the LWC renders correctly

If it works in Incognito, the issue is likely a cached resource — hard-refresh (Ctrl+Shift+R / Cmd+Shift+R) or clear browser cache.

9. Check Console Errors and Network Requests

In the browser Developer Tools (F12):

• Console tab — Look for [LWC error], LWS violation, Apex error, or 404 errors.

• Network tab — Look for failed Apex controller calls (status 500 or 403).

• Application tab — Check if Service Worker is interfering with requests.

10. ECv2 (Enhanced Chat v2) — CLT-Specific Troubleshooting

Custom Lightning Types are only supported in Enhanced Chat v2 (ECv2). If you are deploying via Embedded Messaging, all of the following must be correctly configured for CLT to render.

Step 1 — Verify ECv2 Connection in Agent Builder:

• Open your agent in Agentforce Builder → Connections

• Confirm Enhanced Chat V2 is added as a connection

Do NOT add a Telephony connection alongside ECv2 for standard Service Agents (only AgentScript agents in Agentforce Studio support both)

Step 2 — Verify Embedded Service Deployment Version:

• Go to Setup → Embedded Service Deployments

• Confirm the deployment's Client Version is set to WebV2 (not V1)

• See: Connect a Service Agent to Enhanced Chat v2.

Step 3 — Re-publish the Embedded Service Deployment:
Lightning Type metadata is bundled at publish time. You must re-publish the Embedded Service deployment after any of the following changes:

• Changing the Service Agent under Omni-Channel Routing

• Adding new actions to the agent

• Editing inputs or outputs for any existing actions

• Changing the Output Rendering type for any output

• Activating a different version of the agent

Important: Forgetting to re-publish after configuration changes is one of the most common causes of CLT not rendering in ECv2. Always re-publish after any agent or action change.

Step 4 — Verify Agent User Profile Access:

• Ensure the Agent User Profile and Sys Admin Profile have access to all invocable Apex classes and Flows used by the agent

• See: Set Apex Class Access from Profiles

Step 5 — Diagnose via /sse Request in Dev Tools:
To determine whether the rendering pipeline is receiving the correct format:

1. Open browser Developer Tools → Network tab

2. Filter for /sse requests

3. Inspect the CONVERSATION_MESSAGE event payload

4. Check the formatType field:

   1. formatType: ExperienceType = rendering pipeline is correct

   2. formatType: Text = CLT is falling back to plain text — check ECv2 connection and re-publish

Step 6 — Fix 401 Unauthorized Error for CLT in Experience Cloud / ECv2:
If CLT renders for internal users but throws a 401 Unauthorized error for Experience Cloud site users:

• CLT/LWC does not automatically inherit the logged-in Experience Cloud site user's context

• Fix: Mirror Experience Cloud site membership on the Embedded Service (ESW) site:

  • Go to Setup → All Sites → Workspaces → Administration → Members

  • Add the same user profiles/permission sets that are members of the Experience Cloud site to the ESW site

11. Troubleshoot Custom Lightning Types (CLT) — Input & Output

If your LWC is wired as a CLT Editor (input) or CLT Renderer (output), three alignments must be correct for rendering to work:
For CLT Input (Editor):

1. AgentScript action input must have is_user_input: True and complex_data_type_name pointing to the Lightning Type bundle

2. The Lightning Type Bundle's editor.json (under lightningDesktopGenAi/) must point to the correct LWC

3. The LWC must target lightning__AgentforceInput with the matching targetType

For CLT Output (Renderer):

1. AgentScript action output must have is_displayable: True, filter_from_agent: False, and complex_data_type_name set

2. The Lightning Type Bundle's renderer.json must point to the correct LWC

3. The LWC must target lightning__AgentforceOutput with the matching sourceType

Common CLT Misconfigurations

Tool names between Agent Type

Common Scenarios

1. Custom LWC components do not render inside Agentforce Chat on iPad (including LSC iPad app). The component works correctly on desktop/LEX but displays raw JSON or fails to render on iPad.

2. The LWC button rendered on the first attempt (and sometimes second) but stopped rendering on subsequent turns even though the action was successfully invoked.

   Fix: Review the configuration. Ensure is_displayable: True and filter_from_agent: False are set on the output parameter, and add explicit topic-level instruction: "ALWAYS include the returned LWC component in your response on every turn."

3. CLT Not Rendering with Chained Actions
   When an agent calls two actions where one action's output is passed as input to a second action with CLT, the CLT component does not load. The agent bypasses the CLT-rendered questions and executes the action with the chained input directly.

   Fix: Ensure topic instructions explicitly separate the two action calls and instruct the agent to always invoke the CLT user_input tool before passing data downstream.

4. CLT Not Rendering in Quote Context: CLT was rendering without quote context but not when the user's input included a Quote context.

   Check: Ensure the AgentScript topic instructions do not restrict action execution based on record context. The CLT action must still be called (and show_command used) regardless of whether the context includes a Quote object.

5. CLT Not Rendering in NGA (New Agentforce Builder) for ECv2 Connections
   Currently NGA does not return FormMessage/ExperienceType for ECv2 connections right now — it collects form inputs as plain text messages or blank instead of rendering the CLT input form. This affects CLTs that rely on ECv2 (Enhanced Chat v2) connections in NGA.

6. show_result_tool Not Available:
   If is_displayable is not set on the AgentScript action output, the show_result_tool will not appear in the agent's available tool list during reasoning. This means the agent has no mechanism to render the CLT output, even if the LWC and Lightning Type Bundle are correctly configured.

   Fix: Add is_displayable: True to the action output in the sub_agent's reasoning block + apply prompt tuning to instruct the agent to use the show_result_tool
   
   

7. CLT Not Rendering as Clickable Buttons on Enhanced Chat v2 (Messaging) Surface
   The __show_tool_results__ tool is not available as a callable tool to the LLM for an Agentforce Service Agent on the Enhanced Chat v2 (messaging) surface, causing CLTs to not render as interactive clickable buttons.
   
   Fix: Apply prompt tuning to explicitly instruct the agent to invoke __show_tool_results__ when rendering CLT output on the ECv2 messaging surface.

Important : After saving any CLT-related changes in Agent Builder, always reload the agent page before testing. Changes may not take effect until the page is refreshed.