When the user is experiencing issues with stripe-sync-engine. Also use when the user mentions "not working," "webhook error," "signature failed," "connection error," "data not syncing," or "stripe sync broken."
You are an expert in debugging stripe-sync-engine issues. Your goal is to help users diagnose and fix common problems with their Stripe sync setup.
Ask the user:
Error: Webhook signature verification failed or No signatures found matching the expected signature
Causes and Solutions:
# Check your environment variable
echo $STRIPE_WEBHOOK_SECRET
# Should start with whsec_
# For local development, use the secret from `stripe listen` output
Solution: Get the correct secret:
stripe listen --forward-to localhost:3000/api/webhooks/stripeIf using a framework that auto-parses JSON, the raw body is lost.
Next.js Pages Router Fix:
// pages/api/webhooks/stripe.ts
export const config = {
api: {
bodyParser: false, // Critical! Disable body parsing
},
};
import { buffer } from 'micro';
export default async function handler(req, res) {
const payload = await buffer(req); // Get raw body
await stripeSync.processWebhook(payload, signature);
}
Next.js App Router Fix:
// Use arrayBuffer, not json()
const arrayBuffer = await request.arrayBuffer();
const payload = Buffer.from(arrayBuffer);
// Wrong
await stripeSync.processWebhook(JSON.stringify(body), sig);
// Correct
await stripeSync.processWebhook(rawPayload, sig); // Buffer or string from req.text()
Error: Connection terminated unexpectedly or ECONNREFUSED
Solutions:
# Verify DATABASE_URL format
# postgresql://username:password@host:port/database
# Test connection
psql $DATABASE_URL -c "SELECT 1"
// For remote databases requiring SSL
const stripeSync = new StripeSync({
poolConfig: {
connectionString: process.env.DATABASE_URL,
ssl: {
rejectUnauthorized: false, // For self-signed certs
},
},
// ...
});
Special characters in password need URL encoding:
// If password contains @, encode it as %40
// p@ssword -> p%40ssword
Error: Too many connections or remaining connection slots are reserved
Solutions:
const stripeSync = new StripeSync({
poolConfig: {
connectionString: process.env.DATABASE_URL,
max: 5, // Reduce from default 10
idleTimeoutMillis: 10000, // Close idle connections faster
},
});
For serverless environments, use a connection pooler like:
# Use pooled connection for serverless
DATABASE_URL=postgresql://user:[email protected]:6543/db?pgbouncer=true
Symptoms: Webhook returns success but data not in database
Diagnostic Steps:
SELECT schema_name FROM information_schema.schemata
WHERE schema_name = 'stripe';
If missing, run migrations:
npm run stripe:migrate
SELECT table_name FROM information_schema.tables
WHERE table_schema = 'stripe';
Add logging:
export async function POST(request: Request) {
console.log("Webhook received");
const payload = await request.arrayBuffer();
console.log("Payload size:", payload.byteLength);
await stripeSync.processWebhook(Buffer.from(payload), signature);
console.log("Sync completed");
}
Go to Webhooks > Your Endpoint > Recent Deliveries to see:
Error: permission denied for schema stripe
Solution:
-- Grant permissions
GRANT CREATE ON DATABASE your_database TO your_user;
GRANT ALL ON SCHEMA stripe TO your_user;
-- Or create schema first
CREATE SCHEMA IF NOT EXISTS stripe;
Error: relation already exists
Solution: Migrations track state in stripe_migrations table. If corrupt:
-- Check migration state
SELECT * FROM stripe.stripe_migrations;
-- If needed, reset (careful!)
TRUNCATE stripe.stripe_migrations;
Error: Cannot use Node.js module in Edge Runtime
Cause: stripe-sync-engine requires Node.js runtime, not Edge.
Next.js Fix:
// app/api/webhooks/stripe/route.ts
export const runtime = 'nodejs'; // Force Node.js runtime
Cloudflare Workers: Use the forwarding pattern - Workers verify the signature, then forward to a Node.js service that runs stripe-sync-engine.
Symptoms: Works locally, fails in production
Diagnostic:
// Add to your API route temporarily
console.log("DATABASE_URL set:", !!process.env.DATABASE_URL);
console.log("STRIPE_SECRET_KEY set:", !!process.env.STRIPE_SECRET_KEY);
console.log("STRIPE_WEBHOOK_SECRET set:", !!process.env.STRIPE_WEBHOOK_SECRET);
Common Issues:
.env.local but platform expects .envError: TypeScript errors after installation
Solution:
# Ensure types are installed
npm install -D @types/pg
# If using strict mode, add to tsconfig.json
{
"compilerOptions": {
"skipLibCheck": true
}
}
Enable verbose logging:
import pino from "pino";
const logger = pino({
level: "debug",
transport: {
target: "pino-pretty",
},
});
const stripeSync = new StripeSync({
// ... other config
logger: logger,
});
Create a diagnostic endpoint:
// app/api/health/stripe/route.ts
import { NextResponse } from "next/server";
import { stripeSync } from "@/lib/stripeSync";
export async function GET() {
const checks = {
env: {
DATABASE_URL: !!process.env.DATABASE_URL,
STRIPE_SECRET_KEY: !!process.env.STRIPE_SECRET_KEY,
STRIPE_WEBHOOK_SECRET: !!process.env.STRIPE_WEBHOOK_SECRET,
},
database: false,
schema: false,
};
try {
// Test database connection
const { Pool } = await import("pg");
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await pool.query("SELECT 1");
checks.database = true;
// Check schema exists
const result = await pool.query(
"SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'stripe'"
);
checks.schema = result.rows.length > 0;
await pool.end();
} catch (error) {
// checks remain false
}
const healthy = Object.values(checks.env).every(Boolean) &&
checks.database &&
checks.schema;
return NextResponse.json({ healthy, checks }, { status: healthy ? 200 : 500 });
}
If issues persist: