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

# Troubleshooting

> Fix common issues and optimize your FlipsideAI experience

Running into issues? Here's how to troubleshoot common problems and get FlipsideAI back on track.

## Context window drift

### The problem

Long conversations lose memory of earlier messages. FlipsideAI may:

* Forget details you mentioned earlier
* Contradict itself
* Lose track of your original goal

### Why it happens

AI models have a limited "context window"—a maximum amount of text they can remember. Long chats
exceed this limit.

### Solutions

<AccordionGroup>
  <Accordion title="Summarize key findings" icon="list-check">
    Periodically ask:

    ```text theme={null}
    "Summarize what we've found so far in 5 bullet points"
    ```

    Copy the summary, then start a fresh chat with that context.
  </Accordion>

  <Accordion title="Start new chats for new topics" icon="plus">
    Don't try to tackle multiple unrelated analyses in one conversation. Split them: - Chat 1: Aave
    TVL analysis - Chat 2: Uniswap liquidity research - Chat 3: Cross-chain bridge volumes
  </Accordion>

  <Accordion title="Restate context explicitly" icon="rotate">
    If FlipsideAI seems confused, restate your goal: `text "To recap: we're analyzing Arbitrum DEX
          volumes over Q1 2024, focusing on the top 5 protocols. So far we've looked at Uniswap and Curve.
          Now let's examine SushiSwap." `
  </Accordion>

  <Accordion title="Use Teams for long-term projects" icon="users">
    [Teams](/flipsideai/teams) let you organize multi-conversation projects without losing context across chats.
  </Accordion>
</AccordionGroup>

## Hallucinations

### The problem

FlipsideAI gives you numbers or insights that seem plausible but are incorrect.

### Why it happens

LLMs can "hallucinate"—generate confident-sounding answers that aren't grounded in data. This
happens when:

* The model misinterprets a query
* Data is ambiguous or incomplete
* The model fills gaps with plausible-sounding guesses

### How to detect

<Warning>
  Watch for red flags: - **Suspiciously perfect numbers**: Round figures that seem too convenient -
  **Unrealistic scale**: TVL of \$10B for a tiny protocol - **Contradictions**: Numbers that don't
  match earlier responses - **Vague sourcing**: No clear query or data table referenced
</Warning>

### Solutions

<AccordionGroup>
  <Accordion title="Expand every Flipside Data box" icon="expand">
    Always check:

    * The SQL query used
    * The raw data returned
    * Whether the filters make sense

    If something looks off, the query might be wrong.
  </Accordion>

  <Accordion title="Ask for step-by-step explanations" icon="shoe-prints">
    ```text theme={null}
    "Explain how you calculated this TVL number step by step"
    ```

    Walking through the logic helps catch errors.
  </Accordion>

  <Accordion title="Cross-check with external sources" icon="link">
    Verify against:

    * DeFiLlama (for TVL)
    * CoinGecko/CMC (for prices)
    * Dune Analytics (for volumes)
    * Protocol dashboards

    If Flipside's numbers diverge significantly, investigate why.
  </Accordion>

  <Accordion title="Request validation" icon="check-double">
    ```text theme={null}
    "These results seem high. Can you validate using an alternative approach?"
    "Cross-check this TVL against DeFiLlama data"
    ```

    FlipsideAI can recalculate using different methods.
  </Accordion>
</AccordionGroup>

## Query errors

### The problem

Queries fail to execute or time out.

### Common causes

* **Too much data**: Query spans too many rows or too long a time period
* **Complex joins**: Multiple table joins slow down execution
* **Incorrect table names**: Typo or outdated table reference
* **Schema mismatches**: Trying to join incompatible columns

### Solutions

<AccordionGroup>
  <Accordion title="Narrow date ranges" icon="calendar">
    Instead of:

    ```text theme={null}
    "Show me all Uniswap swaps ever"
    ```

    Try:

    ```text theme={null}
    "Show me Uniswap swaps over the past 30 days"
    ```

    Smaller date ranges = faster queries.
  </Accordion>

  <Accordion title="Specify chains/tokens" icon="filter">
    Instead of:

    ```text theme={null}
    "Show me all DEX activity"
    ```

    Try:

    ```text theme={null}
    "Show me DEX activity on Arbitrum for USDC and ETH"
    ```

    Filtering reduces query size.
  </Accordion>

  <Accordion title="Use curated tables" icon="table">
    Flipside's `ez_*` tables (e.g., `ez_dex_swaps`) are optimized and faster than raw fact tables.

    ```text theme={null}
    "Use the ethereum.defi.ez_dex_swaps table instead of fact_event_logs"
    ```
  </Accordion>

  <Accordion title="Break into steps" icon="stairs">
    For complex analyses, break into sequential queries:

    ```text theme={null}
    "First, show me total DEX volumes.
    Then, break down by protocol.
    Finally, add time series data."
    ```

    Sequential queries are more reliable than one massive query.
  </Accordion>

  <Accordion title="Ask FlipsideAI to retry with a different table" icon="rotate">
    ```text theme={null}
    "That query failed. Can you try using a different table?"
    ```

    Alternative tables may have the same data with a better schema.
  </Accordion>
</AccordionGroup>

## Performance issues

### The problem

Queries are slow or FlipsideAI takes a long time to respond.

### Solutions

<AccordionGroup>
  <Accordion title="Limit results" icon="layer-minus">
    Add explicit limits:

    ```text theme={null}
    "Show me the top 10 protocols by volume (limit to 10 rows)"
    ```

    This prevents returning millions of rows.
  </Accordion>

  <Accordion title="Provide contract addresses" icon="address-card">
    Filtering by address is faster than filtering by token symbol:

    ```text theme={null}
    "Analyze transfers for 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC)"
    ```

    Symbols can be ambiguous; addresses are precise.
  </Accordion>

  <Accordion title="Use aggregated tables" icon="database">
    For high-level metrics, use daily or hourly aggregates instead of transaction-level data: `text
          "Use the ez_core_metrics_hourly table for Solana stats" `
  </Accordion>

  <Accordion title="Avoid wildcard queries" icon="asterisk">
    Don't ask for "everything":

    ```text theme={null}
    ❌ "Show me all token transfers on Ethereum"
    ✅ "Show me USDC transfers on Ethereum over the past 7 days"
    ```
  </Accordion>
</AccordionGroup>

## Incorrect or unexpected results

### The problem

The numbers don't match your expectations or known benchmarks.

### Common causes

* **Token vs USD amounts**: Confusing raw token balances with USD values
* **Duplicate counting**: Rows are joined incorrectly, inflating counts
* **Wrong filters**: Date ranges, chains, or protocols don't match your intent
* **Data gaps**: Some chains or protocols may have incomplete historical data

### Solutions

<AccordionGroup>
  <Accordion title="Clarify units" icon="ruler">
    ```text theme={null}
    "Are these values in USD or in token units?"
    "Convert all amounts to USD using hourly prices"
    ```
  </Accordion>

  <Accordion title="Inspect the SQL" icon="code">
    Expand the Flipside Data box and check:

    * Filters (WHERE clauses)
    * Joins (JOIN conditions)
    * Aggregations (SUM, COUNT, AVG)

    If something looks wrong, point it out:

    ```text theme={null}
    "This query is joining on the wrong column. It should join on tx_hash, not block_number."
    ```
  </Accordion>

  <Accordion title="Sanity-check the numbers" icon="calculator">
    Compare to known benchmarks:

    * Does this TVL match DeFiLlama?
    * Are these volumes consistent with protocol dashboards?
    * Do user counts align with Dune or Token Terminal?

    If not, dig into why.
  </Accordion>

  <Accordion title="Ask for recalculation" icon="arrows-rotate">
    ```text theme={null}
    "This TVL seems low. Recalculate including LP tokens and staked assets."
    ```
  </Accordion>
</AccordionGroup>

## Workflows not triggering

### The problem

You expect a [Workflow](/flipsideai/workflows) to activate, but FlipsideAI uses general mode
instead.

### Why it happens

* Your prompt doesn't match the Workflow's trigger keywords
* The Workflow doesn't exist for your use case
* FlipsideAI misinterprets your intent

### Solutions

<AccordionGroup>
  <Accordion title="Manually select the Workflow" icon="at">
    Use the `@` symbol to browse and select:

    ```text theme={null}
    @TVL-Analysis Compare Aave and Compound
    ```
  </Accordion>

  <Accordion title="Use explicit keywords" icon="key">
    Include Workflow-specific terms: - For TVL Workflow: "calculate TVL" or "total value locked" - For
    cohort Workflow: "cohort analysis" or "user retention" - For liquidity Workflow: "liquidity depth"
    or "LP behavior"
  </Accordion>

  <Accordion title="Check if the Workflow exists" icon="magnifying-glass">
    Ask:

    ```text theme={null}
    "Is there a Workflow for analyzing bridge volumes?"
    ```

    If not, use general mode or request a new Workflow.
  </Accordion>
</AccordionGroup>

## Live Query Mode not working

### The problem

You want real-time data, but FlipsideAI uses historical tables instead.

### Why it happens

Live Query Mode must be explicitly requested—it's not enabled by default.

### Solution

Use explicit language:

```text theme={null}
"Use live query to get the current WETH balance for this address"
"Query the node for real-time pool liquidity"
"Fetch live pricing data for ETH"
```

Keywords: "live query," "current," "real-time," "query the node."

## Artifacts not rendering

### The problem

Artifact generation fails or the artifact displays incorrectly.

### Common causes

* Too much data for the visualization
* Complex interactions causing rendering issues
* Browser compatibility problems

### Solutions

<AccordionGroup>
  <Accordion title="Simplify the visualization" icon="wand-magic-sparkles">
    ```text theme={null}
    "Reduce this to the top 10 data points"
    "Remove interactive filtering"
    "Use a simpler chart type (line instead of scatter)"
    ```
  </Accordion>

  <Accordion title="Refresh or try a different browser" icon="browser">
    * Refresh the page - Try Chrome, Firefox, or Edge - Disable browser extensions that might
      interfere
  </Accordion>

  <Accordion title="Request a different format" icon="image">
    ```text theme={null}
    "Instead of an interactive artifact, generate a static PNG"
    ```
  </Accordion>
</AccordionGroup>

## Data freshness issues

### The problem

Data seems outdated or doesn't include the latest activity.

### Why it happens

Flipside's tables are updated periodically (hourly, daily, etc.), not in real-time.

### Solutions

<AccordionGroup>
  <Accordion title="Check table freshness" icon="clock">
    Ask:

    ```text theme={null}
    "When was the ethereum.defi.ez_dex_swaps table last updated?"
    ```

    FlipsideAI can tell you data latency.
  </Accordion>

  <Accordion title="Use Live Query Mode" icon="bolt">
    For truly current data: `text "Use live query to get the latest pool state" `
  </Accordion>

  <Accordion title="Adjust your time range" icon="calendar-days">
    Avoid queries that end "today"—use yesterday or earlier:

    ```text theme={null}
    ❌ "Show me activity through today"
    ✅ "Show me activity through yesterday"
    ```
  </Accordion>
</AccordionGroup>

## Pro tips for avoiding issues

<AccordionGroup>
  <Accordion title="Start simple, then build complexity" icon="layer-plus">
    Begin with a basic query, verify it's correct, then add layers:

    1. "Show me Uniswap volumes" (verify this works)
    2. "Break it down by pool" (add complexity)
    3. "Add time series" (add more complexity)
  </Accordion>

  <Accordion title="Be explicit about everything" icon="bullseye">
    * Specify chains: "on Arbitrum" - Specify time periods: "from 2024-01-01 to 2024-03-31" - Specify
      tokens: "USDC (0xA0b86991...)" - Specify what you want: "in USD, not token units"
  </Accordion>

  <Accordion title="Use Rules for consistency" icon="sliders">
    Save troubleshooting patterns as [Rules](/flipsideai/rules): `text Rule: "Always validate TVL
          results against DeFiLlama before finalizing" `
  </Accordion>

  <Accordion title="Ask clarifying questions" icon="circle-question">
    If results look off:

    ```text theme={null}
    "Walk me through how you calculated this"
    "What tables did you use?"
    "Why did you choose this approach?"
    ```

    Understanding the methodology helps catch errors.
  </Accordion>
</AccordionGroup>

## Still stuck?

If you've tried these solutions and still can't resolve the issue:

1. **Simplify your question**: Break it into smaller parts
2. **Start a new chat**: Context drift may be causing confusion
3. **Try a different approach**: Ask the same question in a different way
4. **Check the docs**: Other pages in this guide may have specific solutions
5. **Reach out for support**: Contact Flipside support with details about the issue

## Next steps

<CardGroup cols={2}>
  <Card title="Data & results" icon="database" href="/flipsideai/data-and-results">
    Deep dive into validating and working with data
  </Card>

  <Card title="Analysis modes" icon="gears" href="/flipsideai/analysis-modes">
    Understand how different modes handle queries
  </Card>

  <Card title="Effective prompting" icon="pen" href="/flipsideai/prompting">
    Craft better prompts to avoid issues
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/flipsideai/workflows">
    Use Workflows for complex, reliable analyses
  </Card>
</CardGroup>