troubleshooting_skill

Overview

This skill helps debug and resolve common issues with stripe-sync-engine, focusing on webhooks, migrations, database connectivity, and server/runtime mismatches. It guides you through targeted diagnostics and practical fixes so your Stripe data syncs reliably. Use it when you see signature errors, connection failures, missing data, or migration problems.

How this skill works

The skill asks for the exact error message, failing step (migrations, webhooks, backfill, queries), whether the setup is new or previously working, and the environment (local, production, serverless). It then walks through checks for webhook signatures, raw body handling, database connectivity and pooling, migrations, runtime requirements, environment variables, and verbose logging. It gives concrete commands, code snippets, and configuration changes to apply and verify.

When to use it

• You see “Webhook signature verification failed” or signature mismatch errors
• Events are delivered but data is not present in the database
• Database connection errors like ECONNREFUSED or too many connections
• Migrations fail with permission or relation errors
• Running in serverless/edge environment and getting runtime/module errors
• Environment variables differ between local and production

Best practices

• Always use the raw request body for signature verification and disable automatic body parsing where required
• Store correct STRIPE_WEBHOOK_SECRET for each environment; local uses stripe listen secret
• Use pooled connection strings or reduce pool size for serverless deployments
• Run and verify migrations before expecting synced data; check stripe schema and stripe_migrations table
• Enable debug logging and create a health endpoint to surface env, DB, and schema checks
• Ensure Node.js runtime for stripe-sync-engine; forward from edge runtimes to a Node service if needed

Example use cases

• Fixing webhook signature failures by replacing the webhook secret and using raw payloads
• Resolving ‘Too many connections’ by lowering pool max or switching to a pooled DB endpoint
• Diagnosing missing synced records by checking webhook delivery, schema, and table existence
• Recovering from migration state corruption by inspecting stripe.stripe_migrations and re-applying migrations
• Adapting Next.js App or Pages router code to correctly handle raw bodies for stripe-sync-engine