> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting workflow settings

> Resolve common issues with workflow configuration, triggers, actions, and publishing in the HoopAI platform.

When your workflows are not behaving as expected, the issue often traces back to a misconfigured setting. This guide walks you through the most common workflow setting problems in the HoopAI platform and how to fix them.

***

## Common workflow setting issues

### Workflow not triggering

If your workflow is not firing when expected, check the following:

<Steps>
  <Step title="Verify the workflow is published">
    Navigate to **Automation > Workflows** and confirm the workflow status is **Published**, not **Draft**. Workflows in draft mode do not execute.
  </Step>

  <Step title="Check the trigger configuration">
    Open the workflow and click on the trigger step. Ensure:

    * The correct trigger type is selected (e.g., **Form Submitted**, **Tag Added**, **Appointment Booked**)
    * Any required filters are configured correctly
    * The trigger is not restricted to a specific form, calendar, or pipeline that does not match the expected input
  </Step>

  <Step title="Review enrollment settings">
    Click on **Settings** in the workflow builder and check the enrollment options:

    * **Allow re-entry** — If disabled, contacts who have already been through this workflow will not enter it again
    * **Enrollment filters** — Confirm filters are not excluding the contacts you expect to enroll
  </Step>

  <Step title="Check for conflicting workflows">
    If another workflow removes the contact, changes a tag, or moves them to a different pipeline stage before this workflow fires, it can prevent enrollment. Review related workflows for conflicts.
  </Step>
</Steps>

***

### Workflow actions not executing

<Steps>
  <Step title="Check for errors in the builder">
    Open the workflow builder and look for the red error icon on any action step. Click it to see details about missing fields or broken integrations.
  </Step>

  <Step title="Review execution logs">
    Go to the **Execution Logs** tab and filter by the affected contact. Check the status of each action — look for **Failed** or **Skipped** entries and review the error details.
  </Step>

  <Step title="Verify action configuration">
    Open the specific action step and confirm:

    * All required fields are filled in
    * Custom field mappings reference fields that still exist
    * Any linked integrations (email, SMS, webhooks) are still connected and authorized
  </Step>
</Steps>

***

### Wait steps not behaving correctly

<Note>
  Wait steps use the account's timezone by default. If contacts are progressing through wait steps at unexpected times, check the timezone setting under **Settings > Business Profile**.
</Note>

Common wait step issues include:

| Issue                  | Cause                                              | Fix                                                                              |
| ---------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
| Contacts skip the wait | Wait duration set to zero or condition already met | Edit the wait step and set a valid duration or condition                         |
| Contacts stuck on wait | Wait condition is never satisfied                  | Review the condition logic — ensure the expected event or field change can occur |
| Wait timing is off     | Timezone mismatch                                  | Verify the account timezone in business profile settings                         |

***

### If/Else conditions routing incorrectly

<Steps>
  <Step title="Check condition logic">
    Open the If/Else step and review each branch's conditions. Ensure operators (equals, contains, is not empty) match your intent.
  </Step>

  <Step title="Verify custom field values">
    If the condition checks a custom field, confirm the field exists and the contact has a value set. Empty fields may route to the **Else** branch unexpectedly.
  </Step>

  <Step title="Test with a known contact">
    Use the **Test Workflow** button, select a contact whose data you know, and verify they follow the expected branch.
  </Step>
</Steps>

***

## Publishing and saving issues

<Warning>
  Changes to a workflow are not active until you click both **Save** and **Publish**. If you only save without publishing, the workflow continues to run with the previously published version.
</Warning>

* If the **Publish** button is grayed out, there are unresolved errors in the workflow. Check for the red error icon on trigger and action steps.
* If the workflow reverts to **Draft** after publishing, check for required fields or integration errors that prevent a valid publish.

***

## Best practices

<Tip>
  Always test your workflow with a real contact before relying on it in production. Use the **Test Workflow** button in the builder and review the execution logs immediately after.
</Tip>

* Name your workflows descriptively so you can identify them quickly
* Add internal notes to complex action steps explaining the intended behavior
* Use unique triggers per workflow to avoid race conditions
* Review execution logs regularly to catch issues early

***

## FAQs

<AccordionGroup>
  <Accordion title="Why is my workflow stuck in draft mode?">
    Workflows stay in draft if there are unresolved errors, such as missing required fields or disconnected integrations. Check each step for the red error icon and resolve all issues before publishing.
  </Accordion>

  <Accordion title="Can I edit a published workflow without stopping it?">
    Yes, you can edit a published workflow. However, your changes will not take effect until you save and re-publish. Contacts currently in the workflow will continue with the version that was active when they enrolled.
  </Accordion>

  <Accordion title="How do I know if a contact was enrolled in my workflow?">
    Go to the **Enrollment History** tab in the workflow. You can search by contact name or filter by date and status to find specific contacts.
  </Accordion>
</AccordionGroup>