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.

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. 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 Fin Thoughts and click See more. 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.

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 in the conversation events.

Common Procedure failures

If Fin is not working as expected, it's usually due to how instructions are phrased or how logic is branched.

Procedure isn't triggering at all

Before reviewing the numbered failures below, run through these basics first:

Check the procedure is published: Draft procedures won't trigger for customers. Confirm the status is set to Published in the editor.
Check Simple Deploy is active: If Simple Deploy is off, Fin won't run any procedures. Go to Fin AI Agent > Deploy > Chat and confirm Fin is enabled.
Check audience targeting: A common miss is targeting Users when the customer is a Lead (or vice versa). In the "When to use this procedure" section, click the audience button and verify the correct audience type and channel are selected.
Check for higher-priority workflows: Active workflows run before Fin evaluates procedure intent. Review your workflows to make sure none are intercepting the conversation before Fin can trigger the procedure.
Review trigger criteria scope: Criteria that are too narrow prevent Fin from matching valid customer messages. Check the "When to use this procedure" description and add positive examples (messages that should trigger it) and negative examples (messages that should not).

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. If a new procedure shares similar trigger criteria with an existing published procedure, the published one may take priority. To isolate the new procedure during testing: temporarily exclude your test user from the existing procedure by adjusting its audience criteria, or narrow the new procedure's trigger to a unique phrase only you would send. Use Fin's thoughts > Expand thoughts in the conversation debugger to confirm which procedure actually fired.

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.

4. Help Center content taking priority

Problem: Fin answers from the Help Center instead of running the procedure, even when the customer's intent clearly matches the procedure's trigger criteria.

Solution: If Fin is defaulting to a Help Center answer instead of running the procedure, there are two approaches depending on your setup. Try Option 1 first — if the issue persists, move to Option 2.

Option 1: Enable Procedure Switching
Agentic Switch is a per-procedure setting that allows Fin to automatically switch from the current procedure to another live procedure when it detects that a customer's intent has changed mid-conversation — rather than staying locked to the original procedure or falling back to a Help Center answer. When enabled:
- Fin reviews the conversation and all live procedure trigger descriptions to decide when switching would better serve the customer
- If multiple procedures could apply, Fin may ask a clarifying question to select the best one
- Only the source procedure (the one Fin is switching out of) needs the setting on
- The @Switch command can still be used to switch manually
To enable it: Fin AI Agent > Train > Procedures > Settings > Agentic Switch

Option 2: Remove or update conflicting Help Center content
If enabling Agentic Switch doesn't resolve the issue, the most reliable fix is to remove or update the Help Center content Fin is surfacing instead of running the procedure. Fin defaults to Help Center answers when relevant content exists for a topic — so if an article covers the same intent as your procedure, Fin may answer from it directly rather than triggering the procedure.

To identify the conflicting content:
- Find the conversation in your Inbox and open Fin's thoughts.
- Look for references to Help Center articles in the response path.
- Either remove the conflicting article or update it to direct customers to contact support, so Fin routes to the procedure instead.

Example: A company has a procedure that handles refund requests - it collects the order number, checks eligibility, and processes the refund automatically. They also have a Help Center article titled "How do I get a refund?" that explains the refund policy. When a customer messages "I'd like a refund", Fin finds the Help Center article and answers with the policy explanation instead of triggering the procedure. In this case, updating the article to say something like "To request a refund, start a chat and our assistant will walk you through it" removes the conflicting answer and routes customers to the procedure instead.

5. Procedure stalls or exits before completing

Problem: The procedure reaches a certain step and stops, or exits to an end state without completing all the expected steps.

Solution: This is usually caused by design patterns that confuse Fin's ability to track where it is in the procedure. Check for the following:

Redundant "Immediately proceed" statements: If multiple steps include instructions like "immediately proceed to the next step," Fin can re-evaluate already-completed steps instead of advancing. Remove these statements and let Fin move through the procedure naturally based on the flow.
Step-jumping instructions: Phrases like "go back to step 2" or "repeat the verification step" can cause Fin to loop between steps rather than moving forward. Design each step so there is one clear forward path.
Overlapping condition logic: If two conditions can both evaluate as true at the same time, Fin may branch unpredictably or stall. Make sure your conditions are mutually exclusive — only one branch should be true at any point.
Sub-procedure exits without continuing: If a sub-procedure completes but the main procedure doesn't have a clear instruction for what to do next, Fin may treat the sub-procedure's end as the end of the entire flow. In the step that calls the sub-procedure, add an explicit instruction: "Once the sub-procedure is complete, continue to [next step name]."

Use Fin's thoughts > See more in the conversation debugger to identify exactly which step Fin was on when the procedure exited unexpectedly.

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.
Fin calls one connector per turn: If your procedure needs to make multiple connector calls in sequence, each call must be its own distinct step. Fin processes one tool call per conversation turn — it cannot chain multiple connector calls within a single step instruction.

Connector doesn't appear in the procedure editor

Problem: Your data connector is published and configured, but it doesn't show up when you try to add it to a step inside the procedure editor.

Solution: Work through these checks in order:

Confirm the connector is set to Live: Go to Settings > Integrations > Data connectors and check the connector's status. A connector in Draft will not appear in the procedure editor.
Verify at least one action is configured: A connector with no actions defined won't appear as an option in the procedure editor, even if it's Live.
Check your role permissions: Some roles can view connectors in Settings but can't access them inside the procedure editor. Confirm your role has access to both areas.
Refresh the page: The procedure editor occasionally needs a hard refresh to reflect recently published connectors. Use ⌘ + Shift + R (Mac) or Ctrl + Shift + R (Windows).
Contact Intercom Support: If none of the above resolve it, reach out to Intercom Support with the connector name and your workspace details. Some workspace configurations require a manual step to make a connector available inside the procedure editor.

Connector fails in auto-execute mode

Problem: The data connector is configured to run automatically — without prompting the customer — but it fails silently during a live conversation. Fin escalates or gives an unexpected response, and there's no visible error in the conversation.

Solution: In auto-execute mode, Fin cannot skip over a failed connector step and continue the procedure. If the connector returns an error, Fin treats the entire step as unresolvable and either escalates to a human or falls back to its default behaviour.

There are two ways to handle this:

Modify your external API to return a fallback value: Instead of returning an error when data isn't available (for example, a 404 when an order isn't found), configure your API to return an empty or default result that Fin can act on. This is the most reliable fix because Fin always receives something it can work with.
Add a Condition step after the connector call: Use the status_code output from the connector to branch to a graceful message or a controlled escalation path when the connector fails. See "Advanced failure handling with status_code" in this article for how to set this up.

Connector output doesn't populate conversation attributes

Problem: A data connector step runs and returns the expected data, but the value doesn't appear as a conversation attribute — and later steps in the procedure can't access it.

Solution: Conversation attributes are set at the start of a conversation and cannot be updated in real time while a procedure is running. A connector executing inside a procedure cannot write a new value back to a conversation attribute mid-conversation.

What this means in practice:

Use connector output directly in later steps: The data your connector returns is available as a step output within the procedure. Reference it in subsequent step instructions using the @connector_name output syntax. The value is accessible within the procedure — it just won't appear as a conversation attribute in the Inbox.
To persist data to a conversation attribute: Use a Handoff to workflow step and set the attribute value inside the workflow instead. Note that the procedure will not resume after the handoff, so plan your flow to complete before handing off.

Data connector set to READ instead of UPDATE

Problem: The procedure runs but doesn't collect or store customer input, even though the data connector step appears to execute.

Solution: Check the data connector action type in the relevant step. READ only checks for an existing stored value — it won't prompt the customer for input or save new data. UPDATE collects input from the customer and saves it to the attribute. If your procedure is supposed to gather information from the customer (e.g. an email address, order number, or reason for contact), switch the action type to UPDATE.

Advanced failure handling with status_code

The status_code returned by a data connector call is exposed as an output attribute. You can reference this in a Condition step to branch on specific HTTP response codes, giving you precise control over how Fin handles different failure scenarios rather than relying on a single pass/fail branch.

For example, you can route a 404 (resource not found) to a different message than a 500 (server error), or escalate to a human agent only when a specific error code is returned.

Tip: See How to write code conditions for Fin Procedures for code examples using status_code in a Condition step.

Validating fixes with Simulations

Before setting your Procedure live, use Simulations to verify the fix:

Preview vs. Simulations — which should I use? Preview shows the full customer-facing experience. Using Preview while your procedure is live can expose step messages to real customers. Simulations run the procedure in the background with no customer-facing output — they're the safest way to validate logic and trigger matching before going live.

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?

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?

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?

Yes — Simulations run the full Procedure including any Data connector steps, making them the most reliable way to validate connector behaviour before going live.

Why is my Procedure being blocked by a Workflow?

Workflows run before Fin evaluates procedure intent. If a Workflow is active for the same conversation trigger, it may route the conversation before Fin has a chance to match a procedure. To fix this: review your active workflows for overlapping triggers and ensure the Let Fin Handle block is correctly configured in the workflow path where you want procedures to be available.

Why did my Procedure hand off to a human unexpectedly?

There are two ways a Procedure can hand off to a human:

Default escalation behavior — Fin escalates automatically based on its built-in logic: when a customer clearly asks to speak to a human, when Fin detects strong frustration or anger, or when the customer is stuck in a repetitive loop. This always fires regardless of how your Procedure is configured.
Configured handoff — A Handoff to team step you've added at a specific point in the Procedure, or Procedure-specific guidance you've written that instructs Fin to hand off in a particular scenario.

If the handoff was unexpected, use Fin's thoughts in the conversation debugger to see which type fired and at which step.

Why is my Escalation Guidance not firing inside a Procedure ?

Escalation Guidance doesn't apply inside a Procedure by default — you need to explicitly enable it in the Procedure's Guidance panel:

Open your Procedure, click on the settings wheel in the top right corner of the Instructions editor and click on Guidance.
Select the workspace-level guidance categories you want to apply, including Handover and escalation.
Fin will combine the selected workspace guidance with any custom procedure-specific guidance you've written.

Note: Fin's default escalation behavior (customer asks for a human, frustration detected, repetitive loop) always fires inside a Procedure regardless of Guidance settings. The Guidance panel controls your workspace-level Escalation Guidance and Escalation Rules only.

What's the difference between Handoff to team and Handoff to workflow?

Both steps end the Procedure, but they route the conversation differently:

Handoff to team — Ends the Procedure and hands the conversation to a human teammate. The conversation then follows the escalation path configured in your Deploy workflow after the Let Fin handle (Let Fin handle block) step.
Handoff to workflow — Ends the Procedure and passes the conversation to a specific reusable Workflow you've already built (for example, a satisfaction survey or a specialist routing flow). The Procedure will not resume after the Workflow completes.

Is a Procedure handoff billed as a Fin Outcome?

A Fin Procedure is only billed as a Fin Outcome when the conversation ends in one of two ways:

Resolution — the customer confirms Fin resolved their issue, or doesn't ask for more help after Fin answers.
Procedure Handoff — Fin hands off to a team, teammate, or workflow via a configured Handoff step or procedure-specific guidance you've set up.
In both cases, you're charged $0.99 — and only ever once per conversation, regardless of how many steps Fin ran or how many questions the customer asked.

Note: You won't be charged if a Procedure fails to complete, exits without reaching one of these outcomes, a customer asks to speak to a human at any point, or the conversation ends through Fin’s default escalation behavior or workspace-level escalation rules.

For full details, see Understanding Fin Outcomes.

My Procedure stops mid-conversation — could it be timing out?

Yes. Procedures run within a Let Fin Handle block in your Workflow, and that block has a default inactivity timeout. If a customer takes longer than that to respond, the block may close before the procedure completes. To fix this, open the Let Fin Handle block in your Workflow settings and increase the inactivity timeout to better match your expected conversation length.

Can I use Guidance to trigger a Procedure?

No. Guidance controls how Fin responds and behaves — it cannot start a procedure or route a conversation into one. The two systems are separate: Guidance shapes Fin's tone and escalation rules; Procedures define step-by-step workflows Fin follows when a specific intent is matched.

To switch from one procedure to another mid-conversation, use the @Switch command inside the source procedure, or enable Agentic Switch in the procedure settings (see "4. Help Center content taking priority" in this article).

If you want Fin to intelligently decide when to call a data connector or follow a specific flow based on what the customer says, build that logic into a procedure rather than guidance.

My code condition isn't branching — how do I debug it?

Code conditions fail silently when there's a syntax error or when the data path you're trying to access doesn't exist in the conversation context. Fin won't surface the error directly — it will just follow the Else branch or stall. Here's how to diagnose it:

Open the conversation in the Inbox and enable Show conversation events (see "Accessing the conversation debugger" above).
In Fin's thoughts, check what value Fin received as the input to your condition. If the value is null or undefined, the data path in your code is incorrect.
Check these common data access patterns: • Customer type: inputs["user"]["role"] — returns "user" or "lead" • Connector output: use the exact field name from your connector's response schema • Conversation attribute: inputs["conversation"]["attribute_name"]
Test your code block in a Python interpreter before adding it to the procedure. This catches syntax errors immediately, without needing to run a live conversation.
If the condition evaluates but routes to the wrong branch, add a print() statement in your code block to log the actual value Fin is receiving. The output will appear in the conversation events.

💡Tip

Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts

Fin and Data connectors FAQs

Fin Procedures explained

Quick start: Create a Fin Procedure

Report on Fin Procedures

Building Fin Procedures

Troubleshooting Fin Procedures and Data connectors