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

# Troubleshooting

> Common issues and solutions for Synapse extensions

## Quick Diagnostics

Having issues? Start here:

<Steps>
  <Step title="Check Status">
    Verify each part of the pipeline:

    * ✅ Extension deployed? Check Fly.io logs
    * ✅ Extension released? Check Shopify versions
    * ✅ Added to checkout? Check editor settings
    * ✅ Code correct? Review validation output
  </Step>

  <Step title="Review Logs">
    Check for errors:

    * Browser console (F12)
    * Fly.io deployment logs
    * Shopify function logs
    * GitHub Actions output
  </Step>

  <Step title="Test Locally">
    Reproduce the issue:

    ```bash theme={null}
    npm run dev
    # Test in local environment
    ```
  </Step>

  <Step title="Consult This Guide">
    Find your issue below and follow the solution
  </Step>
</Steps>

## Extension Issues

<AccordionGroup>
  <Accordion title="Extension Not Appearing in Checkout" icon="eye-slash">
    **Symptoms:**

    * Extension doesn't show in checkout
    * Deployment succeeded but nothing visible
    * Works locally but not in production

    **Solution 1: Add to Checkout Editor**

    1. Go to Settings → Checkout → Customize
    2. Look in left sidebar for your extension
    3. Drag extension into desired location
    4. Click Save

    **Solution 2: Check Extension Target**

    Verify target matches your use case:

    ```toml theme={null}
    # shopify.extension.toml
    [[extensions.targeting]]
    target = "purchase.checkout.delivery-address.render-after"
    ```

    Common targets:

    * `purchase.checkout.delivery-address.render-after`
    * `purchase.checkout.payment-method-list.render-after`
    * `purchase.checkout.block.render`
    * `purchase.checkout.cart-line-item.render-after`

    **Solution 3: Verify Release Status**

    ```bash theme={null}
    shopify app versions list
    ```

    Ensure version is "current" not "draft"

    **Solution 4: Check Conditional Rendering**

    Review your code for conditions that might hide it:

    ```tsx theme={null}
    // This might be hiding your extension!
    if (!address) return null;
    if (cartTotal < 50) return null;
    if (someCondition) return null;
    ```
  </Accordion>

  <Accordion title="Extension Shows Blank/White Screen" icon="square">
    **Symptoms:**

    * Extension space is visible but empty
    * No content renders
    * No console errors

    **Solution 1: Check for Early Returns**

    ```tsx theme={null}
    function Extension() {
      const data = useData();
      
      // Add logging
      console.log('Extension rendering', { data });
      
      // Check all return paths
      if (!data) {
        console.log('No data, showing loading');
        return <SkeletonText />;  // Don't return null
      }
      
      return <Content data={data} />;
    }
    ```

    **Solution 2: Verify Component Imports**

    ```tsx theme={null}
    // ❌ Wrong import
    import { Text } from 'react';

    // ✅ Correct import
    import { Text } from '@shopify/ui-extensions-react/checkout';
    ```

    **Solution 3: Check for Errors**

    Wrap in error boundary:

    ```tsx theme={null}
    <ErrorBoundary onError={(e) => console.error(e)}>
      <Extension />
    </ErrorBoundary>
    ```
  </Accordion>

  <Accordion title="Data Not Loading (undefined/null)" icon="database">
    **Symptoms:**

    * Hook returns undefined
    * Data doesn't populate
    * GraphQL query returns null

    **Solution 1: Verify GraphQL Query**

    Check `run.graphql` syntax:

    ```graphql theme={null}
    # ❌ Wrong field name
    query RunInput {
      cart {
        deliveryAddress {  # Field doesn't exist
          country
        }
      }
    }

    # ✅ Correct
    query RunInput {
      cart {
        deliveryGroups {
          deliveryAddress {
            countryCode
          }
        }
      }
    }
    ```

    **Solution 2: Test Query in GraphiQL**

    ```bash theme={null}
    shopify app graphiql
    ```

    Paste your query and verify it works

    **Solution 3: Add Null Checks**

    ```tsx theme={null}
    function Extension() {
      const address = useShippingAddress();
      
      // ❌ Assumes address exists
      const country = address.country;
      
      // ✅ Handles null/undefined
      const country = address?.countryCode ?? 'US';
      
      // ✅ Returns early
      if (!address) {
        return <Text>Please enter shipping address</Text>;
      }
      
      const country = address.countryCode;
    }
    ```
  </Accordion>

  <Accordion title="TypeScript Errors" icon="code">
    **Symptoms:**

    * Build fails with type errors
    * Red squiggles in IDE
    * "Type X is not assignable to type Y"

    **Solution 1: Add Type Guards**

    ```tsx theme={null}
    // ❌ Error: string | undefined not assignable to string
    const country: string = address.country;

    // ✅ Fix with nullish coalescing
    const country: string = address?.country ?? 'US';

    // ✅ Fix with type assertion (if you're sure)
    const country: string = address!.country;

    // ✅ Fix with conditional
    if (address?.country) {
      const country: string = address.country;
      // Use country here
    }
    ```

    **Solution 2: Update Type Definitions**

    ```bash theme={null}
    npm update @shopify/ui-extensions-react
    ```

    **Solution 3: Fix Interface Definitions**

    ```tsx theme={null}
    interface Props {
      // ❌ Optional but used as required
      address?: Address;
    }

    function Component({ address }: Props) {
      // Error: address might be undefined
      console.log(address.country);
    }

    // ✅ Fix: Make required
    interface Props {
      address: Address;
    }

    // OR handle optional properly
    function Component({ address }: Props) {
      if (!address) return null;
      console.log(address.country);
    }
    ```
  </Accordion>
</AccordionGroup>

## Function Issues

<AccordionGroup>
  <Accordion title="Function Not Executing" icon="function">
    **Symptoms:**

    * Discount/shipping/payment not applying
    * No function logs
    * Function seems inactive

    **Solution 1: Verify Function is Active**

    For discount functions:

    1. Go to Discounts in Shopify admin
    2. Find your discount
    3. Check status is "Active"
    4. Verify dates are current
    5. Check usage limits not exceeded

    **Solution 2: Check Function Logs**

    ```bash theme={null}
    shopify app function logs --watch
    ```

    If no logs appear, function isn't being called

    **Solution 3: Test Locally**

    ```bash theme={null}
    cd extensions/my-function
    echo '{"cart":{"lines":[]}}' | cargo run
    # or
    echo '{"cart":{"lines":[]}}' | node src/run.js
    ```

    **Solution 4: Verify Input Query**

    Check `run.graphql` has required fields:

    ```graphql theme={null}
    query RunInput {
      cart {
        lines {
          quantity
          merchandise {
            ... on ProductVariant {
              id
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Function Returns Empty Results" icon="empty-set">
    **Symptoms:**

    * Function executes but doesn't do anything
    * Logs show empty operations
    * Logic seems correct

    **Solution 1: Add Debug Logging**

    ```rust theme={null}
    fn run(input: Input) -> Result<FunctionRunResult> {
        eprintln!("Input: {:?}", input);
        
        let operations = calculate_operations(&input);
        
        eprintln!("Operations: {:?}", operations);
        
        Ok(FunctionRunResult { operations })
    }
    ```

    **Solution 2: Check Logic Conditions**

    ```rust theme={null}
    // Add logging to see what's failing
    let operations = input.cart.lines.iter()
        .filter_map(|line| {
            eprintln!("Processing line: {:?}", line);
            
            if line.quantity < 2 {
                eprintln!("Quantity too low: {}", line.quantity);
                return None;
            }
            
            Some(create_discount(line))
        })
        .collect();

    eprintln!("Total operations: {}", operations.len());
    ```

    **Solution 3: Verify Return Value**

    ```rust theme={null}
    // ❌ Wrong: Returns empty
    Ok(FunctionRunResult {
        operations: vec![],
    })

    // ✅ Correct: Returns operations
    Ok(FunctionRunResult {
        operations: calculated_operations,
    })
    ```
  </Accordion>

  <Accordion title="Function Timeout" icon="clock">
    **Symptoms:**

    * Function exceeds 5ms limit
    * Execution times out
    * Slow performance

    **Solution 1: Use Rust Instead of JavaScript**

    Rust is 10-100x faster:

    ```bash theme={null}
    # Convert JS function to Rust
    shopify app generate extension --template rust-function
    ```

    **Solution 2: Optimize Loops**

    ```rust theme={null}
    // ❌ Slow: Nested loops
    for line in &input.cart.lines {
        for other_line in &input.cart.lines {
            // O(n²) - BAD
        }
    }

    // ✅ Fast: Single pass
    let result = input.cart.lines.iter()
        .filter_map(|line| process(line))
        .collect();  // O(n) - GOOD
    ```

    **Solution 3: Cache Calculations**

    ```rust theme={null}
    // ❌ Recalculates repeatedly
    fn process_lines(lines: &[CartLine]) {
        for line in lines {
            let total = calculate_total(lines);  // BAD
            // ...
        }
    }

    // ✅ Calculate once
    fn process_lines(lines: &[CartLine]) {
        let total = calculate_total(lines);  // GOOD
        for line in lines {
            // Use cached total
        }
    }
    ```

    **Solution 4: Reduce Query Surface**

    Only query fields you need:

    ```graphql theme={null}
    # ❌ Queries too much data
    query RunInput {
      cart {
        lines {
          id
          quantity
          merchandise {
            ... on ProductVariant {
              id
              title
              price
              image { url }
              product {
                id
                title
                description
                tags
                vendor
              }
            }
          }
        }
      }
    }

    # ✅ Only queries necessary fields
    query RunInput {
      cart {
        lines {
          quantity
          merchandise {
            ... on ProductVariant {
              id
            }
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Deployment Issues

<AccordionGroup>
  <Accordion title="Build Failed in Fly.io" icon="xmark">
    **Symptoms:**

    * Fly.io build fails
    * Red status in dashboard
    * Deployment doesn't complete

    **Solution 1: Check Build Logs**

    1. Open Fly.io project
    2. Select service
    3. Click failed deployment
    4. Review build logs for specific error

    **Solution 2: Fix TypeScript Errors**

    ```
    Error: Type 'string | undefined' is not assignable to type 'string'
    ```

    Add type guards (see TypeScript section above)

    **Solution 3: Fix Missing Dependencies**

    ```
    Error: Cannot find module '@shopify/ui-extensions-react'
    ```

    Verify package.json:

    ```json theme={null}
    {
      "dependencies": {
        "@shopify/ui-extensions-react": "^2024.10.0",
        "react": "^18.0.0"
      }
    }
    ```

    **Solution 4: Node Version Mismatch**

    Specify Node version in package.json:

    ```json theme={null}
    {
      "engines": {
        "node": "20.x"
      }
    }
    ```
  </Accordion>

  <Accordion title="Deploy Succeeds But Extension Not Updated" icon="rotate">
    **Symptoms:**

    * Fly.io shows success
    * Extension doesn't reflect changes
    * Old version still showing

    **Solution 1: Hard Refresh Browser**

    ```
    Ctrl+Shift+R (Windows/Linux)
    Cmd+Shift+R (Mac)
    ```

    **Solution 2: Clear Shopify Cache**

    ```bash theme={null}
    shopify app deploy --force --reset
    ```

    **Solution 3: Check Deployed Version**

    ```bash theme={null}
    shopify app versions list
    ```

    Verify latest version is current

    **Solution 4: Manually Release**

    ```bash theme={null}
    shopify app release --version=latest --force
    ```
  </Accordion>

  <Accordion title="GitHub Push Failed" icon="github">
    **Symptoms:**

    * Cannot push to repository
    * Permission denied error
    * Authentication failed

    **Solution 1: Regenerate Token**

    1. Go to GitHub Settings → Developer settings → Personal access tokens
    2. Delete old token
    3. Create new token with `repo` and `workflow` scopes
    4. Update in Synapse settings

    **Solution 2: Check Repository Exists**

    Verify repository at:

    ```
    https://github.com/user-{userId}/synapse-extensions
    ```

    **Solution 3: Check Branch Protection**

    If pushing to `main`, disable branch protection temporarily

    **Solution 4: Force Push (Careful!)**

    ```bash theme={null}
    git push --force origin branch-name
    ```

    ⚠️ Only if you're sure. This overwrites remote history.
  </Accordion>
</AccordionGroup>

## Performance Issues

<AccordionGroup>
  <Accordion title="Slow Extension Load" icon="turtle">
    **Symptoms:**

    * Extension takes > 1 second to appear
    * Checkout feels sluggish
    * Loading spinner shows too long

    **Solution 1: Check Bundle Size**

    ```bash theme={null}
    npm run build -- --stats
    npx webpack-bundle-analyzer dist/stats.json
    ```

    Target: \< 50KB

    **Solution 2: Remove Large Dependencies**

    ```json theme={null}
    // ❌ Remove these if present
    "lodash": "^4.17.21",        // 71KB
    "moment": "^2.29.4",         // 290KB
    "axios": "^1.4.0",           // 31KB

    // ✅ Use these instead
    // Native methods instead of lodash
    // Native Date instead of moment
    // Native fetch instead of axios
    ```

    **Solution 3: Lazy Load Components**

    ```tsx theme={null}
    import { lazy, Suspense } from 'react';

    const HeavyComponent = lazy(() => import('./HeavyComponent'));

    function Extension() {
      return (
        <Suspense fallback={<SkeletonText />}>
          <HeavyComponent />
        </Suspense>
      );
    }
    ```

    **Solution 4: Optimize Re-renders**

    ```tsx theme={null}
    import { memo } from 'react';

    const ExpensiveComponent = memo(({ data }) => {
      // Only re-renders when data changes
      return <div>{/* Complex rendering */}</div>;
    });
    ```
  </Accordion>

  <Accordion title="High Memory Usage" icon="memory">
    **Symptoms:**

    * Browser tab crashes
    * Fly.io out of memory errors
    * Slow performance over time

    **Solution 1: Fix Memory Leaks**

    ```tsx theme={null}
    useEffect(() => {
      const interval = setInterval(() => {
        // Do something
      }, 1000);
      
      // ⚠️ Must cleanup!
      return () => clearInterval(interval);
    }, []);
    ```

    **Solution 2: Avoid Large Data Structures**

    ```tsx theme={null}
    // ❌ Stores entire product catalog
    const [products, setProducts] = useState([]);

    // ✅ Only stores what's needed
    const [productIds, setProductIds] = useState([]);
    ```

    **Solution 3: Use Fly.io paid plan**

    Free tier has limited memory. Upgrade for more resources.
  </Accordion>
</AccordionGroup>

## When to Ask for Help

If you've tried the above solutions and still have issues:

<CardGroup cols={2}>
  <Card title="Gather Information" icon="clipboard">
    Before asking for help, collect:

    * Generation ID
    * Error messages
    * Browser console logs
    * Fly.io build logs
    * Steps to reproduce
    * Expected vs actual behavior
  </Card>

  <Card title="Contact Support" icon="headset">
    Reach out to:

    **Email:** [support@synapsebuilder.org](mailto:support@synapsebuilder.org)

    **Include:**

    * Detailed description
    * All error messages
    * What you've tried
    * Screenshots if helpful
  </Card>

  <Card title="Community Help" icon="users">
    Ask the community:

    * [Shopify Dev Forums](https://community.shopify.com/c/shopify-developers)
    * [Discord](https://discord.gg/shopifydevs)
    * [Stack Overflow](https://stackoverflow.com/questions/tagged/shopify)
  </Card>

  <Card title="Report Bugs" icon="bug">
    Found a bug in Synapse?

    **GitHub:** [l3x3d/synapse/issues](https://github.com/l3x3d/synapse/issues)

    Include minimal reproduction case
  </Card>
</CardGroup>

## Emergency Rollback

If something breaks in production:

<Steps>
  <Step title="Identify Last Working Version">
    ```bash theme={null}
    git log --oneline
    ```

    Find the commit hash of last working version
  </Step>

  <Step title="Revert to That Version">
    ```bash theme={null}
    git checkout <commit-hash>
    git push --force origin <branch-name>
    ```

    This triggers automatic redeployment
  </Step>

  <Step title="Verify Fix">
    Check checkout to ensure issue is resolved
  </Step>

  <Step title="Fix Issue">
    Fix the problem in a new branch, test thoroughly, then merge
  </Step>
</Steps>

## Prevention Tips

Avoid issues before they happen:

* ✅ Test locally before deploying
* ✅ Review MCP validation output
* ✅ Write unit tests for critical logic
* ✅ Monitor Fly.io logs during deployment
* ✅ Test in dev store before going live
* ✅ Use TypeScript strict mode
* ✅ Follow best practices guide
* ✅ Keep dependencies updated
* ✅ Document your changes
* ✅ Use version control properly

## Next Steps

<CardGroup cols={2}>
  <Card title="Debugging" icon="bug" href="/advanced/debugging">
    Learn debugging techniques
  </Card>

  <Card title="Best Practices" icon="star" href="/advanced/best-practices">
    Follow quality standards
  </Card>

  <Card title="Validation" icon="check-circle" href="/concepts/validation">
    Understand MCP validation
  </Card>

  <Card title="Self-Correction" icon="arrows-rotate" href="/concepts/self-correction">
    How errors are auto-fixed
  </Card>
</CardGroup>