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

# Troubleshooting

## When Rules Are Triggered

Rules run automatically during family syncs or can be triggered manually. Understanding when rules execute helps troubleshoot categorization issues.

<AccordionGroup>
  <Accordion title="Manual trigger (user-initiated)">
    Rules can be manually triggered in the following ways:

    * Clicking "Re-apply" on an individual rule in `/settings/rules`
    * Clicking "Apply All" in `/settings/rules`
    * Running the rake task: `bin/rails rules:apply_all[family_id]`
  </Accordion>

  <Accordion title="During family sync (only active rules)">
    Rules with `active: true` run automatically when a family sync occurs (`Family::Syncer.perform_sync`):

    **Scheduled syncs:**

    * `SyncAllJob` - runs daily at 2:22 AM for all families
    * `SyncHourlyJob` - runs every hour (for items that opt-in to hourly syncing)

    **Triggered syncs:**

    * Provider webhooks (Plaid, etc.) - triggers sync which eventually propagates to family
    * Manual sync button on accounts page
    * After CSV imports complete (`Import` model calls `family.sync_later`)
  </Accordion>

  <Accordion title="When rules do NOT run">
    Rules are **not** triggered in these scenarios:

    * **Manual transaction creation** - Only triggers an Account sync (not Family sync)
    * **Manual transaction editing** - Same as above, only Account sync runs
    * **Inactive rules** - Rules with `active: false` never run automatically, only via manual "Re-apply"
  </Accordion>
</AccordionGroup>

## Category Rule Popup Behavior

When a user selects a category for a transaction, a popup may appear to create an automatic categorization rule. This popup is intentionally gated by several conditions:

<AccordionGroup>
  <Accordion title="When does the popup appear?">
    The popup only shows when **all** of these conditions are met:

    1. User has not disabled rule prompts (`rule_prompts_disabled` is false)
    2. User hasn't dismissed the popup in the last **24 hours**
    3. The transaction category actually changed
    4. No existing rule already sets this category for similar transactions
    5. The transaction has a category assigned
  </Accordion>

  <Accordion title="Why isn't the popup showing?">
    Check these common reasons:

    * **Recently dismissed**: Wait 24 hours after dismissing the popup
    * **Rule already exists**: A matching rule may already be in place
    * **Prompts disabled**: Check if `rule_prompts_disabled` is enabled for the user
  </Accordion>
</AccordionGroup>

## Sure Doesn’t Work Over HTTPS

If Sure behaves incorrectly or fails when accessed over HTTPS, it’s usually due to missing SSL-related configuration between Nginx and Rails.

<AccordionGroup>
  <Accordion title="What causes this issue?">
    Sure relies on correct protocol headers to determine whether a request is secure.\
    When HTTPS is terminated at Nginx but not properly forwarded to the app, Rails may treat requests as HTTP.
  </Accordion>

  <Accordion title="How do I fix it?">
    Apply the following configuration changes:

    1. **Nginx**

       Ensure HTTPS is forwarded to the upstream app:

       ```nginx theme={null}
       proxy_set_header X-Forwarded-Proto https;
       ```

    2. **docker-compose.yml**

       In the `x-rails-env: &rails_env` section, set:

       ```yaml theme={null}
       RAILS_ASSUME_SSL: "true"
       ```

       This tells Rails to treat all requests as HTTPS.
  </Accordion>
</AccordionGroup>

## Some pages break over HTTPS

Sure uses WebSockets for certain pages. If some pages fail to render correctly or break entirely, this is often caused by missing SSL or upgrade headers in your reverse proxy configuration.

<AccordionGroup>
  <Accordion title="What are the symptoms?">
    You may see pages partially load, fail completely, or errors similar to:

    ```text theme={null}
    Failed to upgrade to WebSocket (REQUEST_METHOD: GET, HTTP_CONNECTION: close, HTTP_UPGRADE: )
    ```

    This indicates that the WebSocket upgrade request is not being forwarded correctly.
  </Accordion>

  <Accordion title="How do I fix it?">
    Ensure your Nginx configuration includes the required WebSocket headers:

    ```nginx theme={null}
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    ```

    These headers allow Nginx to properly handle WebSocket upgrade requests over HTTPS.
  </Accordion>
</AccordionGroup>

## Why is Sure not running auto-categorization and merchant detection on the same transactions again?

Sure caches AI-generated results to avoid redundant API calls and costs. Once a transaction has been processed by AI rules, it won't be re-processed unless you explicitly reset the AI cache.

<AccordionGroup>
  <Accordion title="Why does Sure cache AI results?">
    When AI rules process transactions, Sure stores:

    * **Enrichment records** - Which attributes were set by AI (category, merchant, etc.)
    * **Attribute locks** - Prevents rules from re-processing already-handled transactions

    This caching ensures:

    * Transactions aren't sent to the LLM repeatedly
    * API costs are minimized
    * Processing is faster on subsequent rule runs
  </Accordion>

  <Accordion title="How do I force Sure to re-process transactions?">
    To have AI rules re-process transactions, you need to reset the AI cache:

    1. Go to **Settings** → **Rules**
    2. Click the menu button (three dots)
    3. Select **Reset AI cache**
    4. Confirm the action

    After resetting, the next time rules run (either manually or during a sync), AI will re-process all transactions.

    **Note:** This will incur API costs if using a cloud provider.
  </Accordion>

  <Accordion title="When should I reset the AI cache?">
    Common scenarios for resetting the cache:

    * **Switching LLM models** - Different models may produce better categorizations
    * **After system updates** - New versions may have improved prompts
    * **Fixing miscategorizations** - When AI made systematic errors
    * **Testing** - During development or evaluation of AI features

    The AI cache is automatically cleared when you change the OpenAI model setting.
  </Accordion>
</AccordionGroup>