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

# Filter Troubleshooting

> Troubleshooting common issues when dashboard or metric filters cause connection errors, SQL syntax errors, or unexpected behavior.

When a filter is selected, you may see a **connection error**, **syntax error**, or **unexpected results**. If the same metric works fine without a filter (or with a hardcoded value), the problem is almost always **filter substitution or value shape**, not credentials or network.

***

## Common Issues and Fixes

<AccordionGroup>
  <Accordion title="Error: 'Filter or Client variables detected in the query'" icon="triangle-exclamation">
    **Cause:** The final SQL query still contains unresolved `{{variable}}` placeholders when it runs. This happens when:

    1. The variable name in the SQL doesn't exactly match the filter's variable name (case-sensitive)
    2. The filter has no value and no default, so nothing gets substituted
    3. The SQL references a variable that no filter provides

    **Fix:** Make the `{{name}}` in your SQL exactly match the filter's variable name, and give the filter a default value so the metric can run before a user makes a selection.

    ```sql theme={"dark"}
    -- Works once the filter named global_region has a value or default
    SELECT * FROM sales WHERE region = {{global_region}}
    ```

    Keep filter variables in the WHERE clause. There is no built-in way to display or "inspect" the current filter value in a metric, so a variable in SELECT has no supported use — do not use `SELECT {{var}}` to debug.
  </Accordion>

  <Accordion title="Syntax error: 'at or near NOT' (with no visible NOT in your query)" icon="code">
    **Cause:** A **multi-select** filter is being used with single-value syntax (`= {{var}}`). When the product substitutes an array of selected values, the resulting SQL can be invalid.

    **Fix:** For multi-select filters, use **IN** syntax instead of `=`. The runtime substitutes the variable as a parenthesized list of quoted values (e.g. `( 'US' , 'CA' )`), so do **not** add your own parentheses:

    ```sql theme={"dark"}
    -- Wrong: multi-select with equality
    WHERE region = {{global_region}}

    -- Wrong: double-wrapped parentheses produce invalid SQL
    WHERE region IN ({{global_region}})

    -- Correct: multi-select with IN, no extra parentheses
    WHERE region IN {{global_region}}
    ```

    See [Dashboard Filter Variable Apply On](/guides/dashboards/create-modify-dashboard-filter/dashboard-filter-variable-apply-on) for single-select vs. multi-select details.
  </Accordion>

  <Accordion title="'Invalid reference to FROM-clause entry for table'" icon="database">
    **Cause:** The filter value shape (array vs. scalar) doesn't match what the SQL expects. Hardcoding the same value works because it's always a scalar.

    **Fix:** Check whether the filter is configured as single-select or multi-select, and adjust your SQL accordingly. For multi-select, use `IN {{var}}` (no extra parentheses).
  </Accordion>

  <Accordion title="Connection error only when a specific filter value is selected" icon="plug">
    **Cause:** The selected filter value may contain **special characters** (e.g., apostrophes, quotes) that break the generated SQL.

    **Fix:**

    * If you control the filter options (e.g., Manual filter), use values that don't contain apostrophes or special SQL characters.
    * For custom SQL filters, ensure your LHS/RHS or Apply on logic handles escaping.
  </Accordion>

  <Accordion title="Error or no data when 'no selection' or blank is chosen" icon="circle-xmark">
    **Cause:** The variable may be substituted as empty or NULL, producing invalid SQL (e.g., `WHERE col = ` with nothing after `=`).

    **Fix:** In your WHERE clause, handle the "no filter" case explicitly if your use case requires optional filtering:

    ```sql theme={"dark"}
    WHERE ('{{global_region}}' = '' OR region = {{global_region}})
    ```

    Check the dashboard filter docs for recommended optional-filter patterns.
  </Accordion>

  <Accordion title="Filter has no effect, or metric_filters is empty" icon="filter-circle-xmark">
    **Cause:** The variable name in your metric's SQL does not match the name configured for the filter.

    **Fix:**

    * Use the **exact variable name** shown when you set up the filter (Apply on > Variable Filter). Copy it from the product UI if possible.
    * Variable names are case-sensitive.
    * In Python console or embed context, `metric_filters` is only populated when: (1) the metric's SQL actually uses that filter variable, (2) the metric runs in a dashboard context with the filter applied, and (3) the variable name matches exactly.
  </Accordion>
</AccordionGroup>

***

## Quick Checklist

| Check                                  | Action                                                                                          |
| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
| "Filter or Client variables detected"? | An unresolved `{{…}}` remains — check name match and default value.                             |
| Multi-select filter?                   | Use `IN {{var}}` (no extra parentheses), not `= {{var}}`.                                       |
| Special characters in values?          | Avoid or escape; use safe values in Manual filter.                                              |
| Empty filter value?                    | Handle "no selection" in WHERE if needed.                                                       |
| Variable name mismatch?                | Must match filter config exactly (case-sensitive).                                              |
| metric\_filters empty?                 | Ensure SQL uses the variable, name matches, and context is a dashboard with the filter applied. |

***

## Related Guides

<CardGroup cols={2}>
  <Card title="Dashboard Filter Variable Apply On" href="/guides/dashboards/create-modify-dashboard-filter/dashboard-filter-variable-apply-on">
    How variable naming works, single-select vs. multi-select, and WHERE clause usage.
  </Card>

  <Card title="Create/Modify Dashboard Filter" href="/guides/dashboards/create-modify-dashboard-filter">
    Full guide to creating and configuring dashboard filters.
  </Card>

  <Card title="LHS/RHS Custom SQL" href="/guides/dashboards/create-modify-dashboard-filter/add-lhs-and-rhs-custom-sql-support-for-dashboard-filter">
    Custom SQL transformations in dashboard filters.
  </Card>
</CardGroup>