Debugging

Overview

Comprehensive debugging guide for identifying and fixing issues in your Synapse-generated extensions and functions.

Debugging Tools

Browser DevTools

Debug UI extensions in checkout

Console logs
Network requests
React DevTools
Performance profiling

Shopify CLI

Local development and logs

shopify app dev
Function logs
Extension preview
GraphQL introspection

Fly.io Logs

Deployment and build logs

Build output
Deploy status
Runtime errors
Environment issues

MCP Validation

Synapse validation output

API compliance
Component usage
Type errors
Best practices

Common Issues

Extension Not Showing
GraphQL Errors
Function Not Applying
Build Failures

Symptoms:

Extension doesn’t appear in checkout
Not visible in admin
Deployment succeeded but nothing shows

Debugging Steps:

Check Deployment Status

shopify app versions list

Verify extension is deployed and released

Verify Extension Configuration

Check shopify.extension.toml:

type = "ui_extension"
name = "delivery-estimate"

[[extensions.targeting]]
target = "purchase.checkout.delivery-address.render-after"

Ensure target matches checkout flow

Add to Checkout Editor

Settings → Checkout → Customize
Find extension in left sidebar
Drag into layout
Save

Check Conditional Logic

Review your component for conditions that might hide it:

// This might hide your extension!
if (cartTotal < 50) return null;

Common Causes:

Wrong extension target
Not added to checkout editor
Conditional rendering hiding it
Extension not released (draft mode)

Symptoms:

“Field not found” errors
Data not loading
Undefined values

Debugging Steps:

Check Console

Open browser DevTools console:

Error: Field 'deliveryAddress' not found on type 'Cart'

Verify GraphQL Query

Check run.graphql:

query RunInput {
  cart {
    deliveryAddress {  # ❌ Wrong
      country
    }
  }
}

Should be:

query RunInput {
  cart {
    deliveryGroups {  # ✅ Correct
      deliveryAddress {
        country
      }
    }
  }
}

Test Query in GraphiQL

Use Shopify GraphiQL to test:

shopify app graphiql

Paste your query and verify it works

Check API Version

Ensure using correct API version in shopify.app.toml:

scopes = "write_products,read_customers"

[app_proxy]
prefix = "apps"

Common Causes:

Typo in field names
Wrong API version
Missing permissions
Incorrect query structure

Symptoms:

Discount/shipping/payment function not working
No errors but function doesn’t execute
Function logs empty

Debugging Steps:

Check Function Logs

shopify app function logs --watch

See if function is being called

Verify Function is Active

For discount functions:

Go to Discounts in admin
Verify discount exists
Check it’s not expired
Ensure it’s active

Test Input/Output

Create test input file:

{
  "cart": {
    "lines": [{
      "quantity": 5,
      "merchandise": {
        "id": "gid://shopify/ProductVariant/123"
      }
    }]
  }
}

Test locally:

cat test-input.json | shopify app function run

Check Return Value

Ensure function returns proper output:

// ❌ Wrong: empty operations
Ok(FunctionRunResult {
    operations: vec![],
})

// ✅ Correct: returns discount
Ok(FunctionRunResult {
    operations: vec![
        Operation::Discount(/* ... */)
    ],
})

Common Causes:

Function not activated in admin
Logic always returns empty
Input query missing data
Function crashes (check logs)

Symptoms:

Fly.io build fails
TypeScript errors
Dependency issues

Debugging Steps:

Check Fly.io Logs

View build output in Fly.io dashboard:

[error] Type 'string | undefined' is not assignable to type 'string'

Fix TypeScript Errors

Add proper type guards:

// ❌ Wrong
const country = address.country;

// ✅ Correct
const country = address?.country ?? 'US';

Verify Dependencies

Check package.json versions:

{
  "dependencies": {
    "@shopify/ui-extensions-react": "^2024.10.0",
    "react": "^18.0.0"
  }
}

Build Locally

Test build before pushing:

npm install
npm run build

Fix any errors locally first

Common Causes:

TypeScript type errors
Missing dependencies
Version conflicts
Syntax errors

Debugging Techniques

Console Logging

Add debug logs to your extensions:

function Extension() {
  const address = useShippingAddress();
  
  console.log('Extension rendered');
  console.log('Shipping address:', address);
  
  useEffect(() => {
    console.log('Address changed:', address);
  }, [address]);
  
  return <YourComponent />;
}

View in browser DevTools → Console

React DevTools

Inspect component state and props:

Install React DevTools
Open checkout in browser
Open DevTools → Components tab
Find your extension component
Inspect props, state, hooks

Useful for:

Checking hook values
Verifying props
Testing renders

Network Debugging

Monitor API calls:

Open DevTools → Network tab
Filter by “Fetch/XHR”
Look for GraphQL requests
Inspect request/response

Check for:

Query variables
Response data
Error messages
Status codes

Function Testing

Test functions locally:

# Navigate to function
cd extensions/my-function

# Create test input
cat > test.json << EOF
{
  "cart": {
    "cost": {
      "subtotalAmount": {
        "amount": "150.00"
      }
    }
  }
}
EOF

# Run function
cargo run < test.json
# or
node src/run.js < test.json

# View output

Performance Debugging

Slow Extension Load

Symptoms: Extension takes long to appearDebug:

DevTools → Performance tab
Record page load
Look for long tasks
Check bundle size

Fixes:

Reduce bundle size
Lazy load components
Optimize images
Remove unused deps

Function Timeout

Symptoms: Function exceeds 5ms limitDebug:

Check function logs for timing
Add timing code:

let start = std::time::Instant::now();
// your logic
eprintln!("Took {:?}", start.elapsed());

Fixes:

Use Rust instead of JS
Minimize loops
Cache calculations
Reduce query surface

Memory Issues

Symptoms: Extension crashes, Fly.io OOMDebug:

DevTools → Memory tab
Take heap snapshots
Check for memory leaks

Fixes:

Clean up event listeners
Avoid large data structures
Use React.memo
Optimize re-renders

Large Bundle

Symptoms: Build size over 50KBDebug:

npm run build -- --stats
npx webpack-bundle-analyzer dist/stats.json

Fixes:

Remove unused imports
Use tree-shaking
Avoid large libraries
Code splitting

Error Messages Reference

Common errors and solutions:

Error	Cause	Solution
`Extension target not found`	Invalid target in toml	Check extension targets docs
`Field not found on type`	GraphQL query error	Verify field exists in schema
`Function execution timeout`	Function too slow	Optimize logic, use Rust
`Permission denied`	Missing API scopes	Add required scopes to app
`Network request failed`	API call failed	Check network, retry logic
`Component not found`	Import error	Verify component name/import
`Type error`	TypeScript mismatch	Add type guards, fix types
`Build failed`	Compilation error	Check Fly.io logs, fix syntax

Advanced Debugging

Remote Debugging
Source Maps
Error Boundaries

Debug deployed extensions:

Open checkout on device
Connect via USB (mobile)
Chrome → chrome://inspect
Select device
Inspect and debug

Debug minified code:

// vite.config.ts
export default {
  build: {
    sourcemap: true,  // Enable source maps
  },
};

Source maps allow debugging original TypeScript in production

Catch and log errors:

import { ErrorBoundary } from '@shopify/ui-extensions-react/checkout';

function Extension() {
  return (
    <ErrorBoundary
      onError={(error, errorInfo) => {
        console.error('Extension error:', error);
        console.error('Error info:', errorInfo);
        
        // Send to logging service
        logError({
          error: error.message,
          stack: error.stack,
          componentStack: errorInfo.componentStack,
        });
      }}
    >
      <YourComponent />
    </ErrorBoundary>
  );
}

Debugging Checklist

Before asking for help:

Getting Help

Synapse Support

Contact support:

Email: support@synapsebuilder.org
Include generation ID
Share error messages
Provide steps to reproduce

Shopify Community

Community resources:

Documentation

Official docs:

GitHub Issues

Report bugs:

Synapse GitHub
Include error logs
Provide minimal reproduction
Tag appropriately

Next Steps

Best Practices

Learn optimization techniques

Troubleshooting

Common issues and solutions

Validation

Understand MCP validation

Self-Correction

How errors are auto-fixed

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

Overview

Debugging Tools

Browser DevTools

Shopify CLI

Fly.io Logs

MCP Validation

Common Issues

Debugging Techniques

Performance Debugging

Slow Extension Load

Function Timeout

Memory Issues

Large Bundle

Error Messages Reference

Advanced Debugging

Debugging Checklist

Getting Help

Synapse Support

Shopify Community

Documentation

GitHub Issues

Next Steps

Best Practices

Troubleshooting

Validation

Self-Correction

​Overview

​Debugging Tools

Browser DevTools

Shopify CLI

Fly.io Logs

MCP Validation

​Common Issues

​Debugging Techniques

​Performance Debugging

Slow Extension Load

Function Timeout

Memory Issues

Large Bundle

​Error Messages Reference

​Advanced Debugging

​Debugging Checklist

​Getting Help

Synapse Support

Shopify Community

Documentation

GitHub Issues

​Next Steps

Best Practices

Troubleshooting

Validation

Self-Correction

Overview

Debugging Tools

Common Issues

Debugging Techniques

Performance Debugging

Error Messages Reference

Advanced Debugging

Debugging Checklist

Getting Help

Next Steps