Skip to main content

​
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:
1

Check Deployment Status

shopify app versions list
Verify extension is deployed and released
2

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
3

Add to Checkout Editor

  1. Settings → Checkout → Customize
  2. Find extension in left sidebar
  3. Drag into layout
  4. Save
4

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)

​
Debugging Techniques

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
Inspect component state and props:
  1. Install React DevTools
  2. Open checkout in browser
  3. Open DevTools → Components tab
  4. Find your extension component
  5. Inspect props, state, hooks
Useful for:
  • Checking hook values
  • Verifying props
  • Testing renders
Monitor API calls:
  1. Open DevTools → Network tab
  2. Filter by “Fetch/XHR”
  3. Look for GraphQL requests
  4. Inspect request/response
Check for:
  • Query variables
  • Response data
  • Error messages
  • Status codes
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:
ErrorCauseSolution
Extension target not foundInvalid target in tomlCheck extension targets docs
Field not found on typeGraphQL query errorVerify field exists in schema
Function execution timeoutFunction too slowOptimize logic, use Rust
Permission deniedMissing API scopesAdd required scopes to app
Network request failedAPI call failedCheck network, retry logic
Component not foundImport errorVerify component name/import
Type errorTypeScript mismatchAdd type guards, fix types
Build failedCompilation errorCheck Fly.io logs, fix syntax

​
Advanced Debugging

  • Remote Debugging
  • Source Maps
  • Error Boundaries
Debug deployed extensions:
  1. Open checkout on device
  2. Connect via USB (mobile)
  3. Chrome → chrome://inspect
  4. Select device
  5. Inspect and debug

​
Debugging Checklist

Before asking for help:
  • Checked browser console for errors
  • Verified extension is deployed and released
  • Added extension to checkout editor (if UI extension)
  • Tested GraphQL queries in GraphiQL
  • Reviewed Fly.io build/deploy logs
  • Checked function logs (if using functions)
  • Tested locally with shopify app dev
  • Verified environment variables are set
  • Confirmed API permissions/scopes
  • Checked for conditional logic hiding components
  • Reviewed MCP validation output
  • Tested with different data/scenarios

​
Getting Help

Synapse Support

Contact support:

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