When a Fin Procedure doesn't resolve a conversation as expected, you can use built-in inspection tools to investigate Fin's decision-making logic. Use this guide to identify where a flow went off track and how to refine your instructions.
What you'll learn
Debug Procedure failures using Fin's thoughts and conversation events.
Diagnose common issues like wrong Procedure triggers, out-of-sequence steps, and branching failures.
Troubleshoot Data connector errors, including auth failures and missing data.
Validate fixes before going live using Simulations.
Note: Fin Procedures are available through managed availability. Please contact your account manager to confirm eligibility or go to Fin AI Agent > Train > Procedures and click "Request Access."
Accessing the conversation debugger
To understand why Fin took a specific action, you must first enable technical visibility within the conversation thread.
Open the specific conversation in the Inbox.
Click the three dots icon at the top right of the conversation header.
Select Show conversation events.
Tip: Use the keyboard shortcut ⌘ + E (Mac) or Ctrl + Shift + E (Windows) to toggle this view.
Inspecting "Fin's thoughts"
Once conversation events are visible, you can see the reasoning behind every step Fin took during a Procedure.
Important: This article covers troubleshooting for Fin Procedures only. The "Fin's thoughts" timeline and debugger are only available when a Procedure was triggered. If Fin gave an unexpected answer in a standard conversation, these tools will not be present.
Reviewing the logic
To trace Fin’s decision-making process, locate the Fin's thoughts events in the conversation timeline. These events summarize Fin’s reasoning before it sends a message or performs an action.
For more granular detail, click the light bulb icon on a thought and select Expand thoughts. This reveals:
The current step: The specific Procedure step Fin was executing.
Intent interpretation: How Fin understood the customer’s request.
Logic path: Why Fin decided to skip a step, revisit a previous one, or move to a specific branch.
Common Procedure failures
If Fin is not working as expected, it's usually due to how instructions are phrased or how logic is branched.
1. Fin triggers the wrong Procedure
Problem: Fin starts a Procedure that doesn't match the customer's request.
Solution: Review your "When to use this procedure" instructions. Use positive and negative examples to help Fin distinguish between similar intents.
2. Steps out of sequence
Problem: Fin skips a prerequisite step or moves to a resolution prematurely.
Solution: Check for ambiguity in your natural language instructions. If a step relies on a specific piece of data, ensure the instruction explicitly states: "Only proceed if [data] is provided."
3. Branching logic failures
Problem: Fin follows the "Else" path when it should have followed the "If" path.
Solution: Inspect the Conditions. If using natural language for branching, try rephrasing for clarity. For complex logic (e.g., date calculations), consider using Python code blocks to enforce strict deterministic rules.
Troubleshooting Data connectors
This section covers failures specific to data connectors running inside a Procedure. If your connector passes standalone testing but fails during a live Procedure run, start here.
Connector works in testing but fails in a live Procedure
Problem: The connector passes standalone tests but fails during a live run.
Solution: This is usually caused by one of the following:
Credentials: Re-save and republish after rotating a key. Check for hidden characters like trailing spaces in token values.
Permissions: A recent security change on your external system may have removed access.
IP allowlisting: Confirm Intercom's outbound IPs are included. Contact your account manager for the current ranges.
Important: If your connector stops working without changes on your side, check if your external API provider (e.g., Shopify, Stripe) has updated or deprecated an endpoint.
401 and 403 authorization errors
401 Unauthorized: The token is missing, expired, or malformed. Intercom retries once automatically. Check the Logs tab to confirm if a refresh was attempted.
403 Forbidden: The token is valid but lacks permission. Review permissions on your external system.
OAuth users: Use the Reauthenticate button instead of deleting and recreating the token.
Connector doesn't appear to be triggering
Check the logs: Navigate to Settings > Integrations > Data connectors > Logs. If there is no log entry, the step was likely skipped; check the preceding branch logic.
Check conversation events: Select Logs from any error event in the Inbox for full details.
Connector returns data but Fin doesn't use it
Use Fin's thoughts to see how Fin interpreted the connector response.
Make the step instruction more explicit: "Use @connector_name to answer this—do not use knowledge base content."
Check if the response is empty or null; Fin may fall back to other sources if no usable data is found.
Validating fixes with Simulations
Before setting your Procedure live, use Simulations to verify the fix:
Navigate to the Procedure editor and click Test.
Run a Simulation where the AI acts as the customer in the failing scenario.
Review the pass/fail result and the AI judgment to confirm the logic is reliable.
FAQs
Does the conversation debugger work for standard Fin conversations?
Does the conversation debugger work for standard Fin conversations?
No, the "Fin's thoughts" timeline and debugger are only available when a Procedure was triggered. If Fin gave an unexpected answer in a standard conversation, these tools won't be present—check the Inbox conversation events instead.
How long are Data connector logs stored?
How long are Data connector logs stored?
Data connector response logs are stored for up to 7 days by default. If your workspace has extended logs enabled, this increases to 14 days. Access them under Settings > Integrations > Data connectors > Logs.
Can I use Simulations to test Data connector responses?
Can I use Simulations to test Data connector responses?
Yes, simulations run the full Procedure including any Data connector steps, making them the most reliable way to validate connector behaviour before going live.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts