Agency Guide
Data Migrations & Troubleshooting
Running data migrations, diagnosing issues, and resolving common platform problems
Overview
Platform updates sometimes require data migrations to update existing records, add new fields, or restructure data. This page covers how to run migrations, diagnose common issues, and access support resources.
Running Migrations
Migration Scripts
Migrations are stored in scripts/migrations/ and named by date and feature:
# List available migrations
ls scripts/migrations/
# Run a specific migration
node scripts/migrations/2026-05-02-meta-ads-foundation.js
# Run the billing engine test suite
node scripts/test-billing-engine.mjs
# Run agent phase tests
node scripts/test-agent.js --phase 34 # Google Ads
node scripts/test-agent.js --phase 35 # Meta Ads
Pre-Migration Checklist
- Backup the database — always create a snapshot before running migrations
- Test in staging — run migrations against a test environment first
- Check dependencies — some migrations require specific env vars to be set
- Schedule downtime — warn users if the migration causes service interruption
- Verify post-migration — run the associated test suite after completion
Never run untested migrations directly against production. Always validate in a staging environment first.
Common Issues
Authentication & Access
| Issue | Resolution |
|---|---|
| Admin login fails | Verify credentials and check that the admin user exists with isActive: true |
| API returns 403 | The user's role may not have the required permission — check RBAC settings |
| OAuth callback fails | Verify the redirect URI matches exactly (including protocol and trailing slashes) |
| Token refresh fails | Check that OAuth client ID and secret match the original app that issued the tokens |
Integrations
| Issue | Resolution |
|---|---|
| GHL sync not working | Verify the OAuth token is valid and the GHL location is connected |
| Google Ads "DEVELOPER_TOKEN_NOT_APPROVED" | Check the token's access level in the API Center |
| Meta webhook 403 | Verify token doesn't match META_WEBHOOK_VERIFY_TOKEN |
| WordPress connection drops | Check REST API credentials and that the site is accessible |
Voice Agents
| Issue | Resolution |
|---|---|
| Agent not answering calls | Verify the phone number is assigned and the agent is active |
| Calls dropping immediately | Check the agent's prompt configuration and provider settings |
| No recording available | Verify Twilio recording settings and the recording-status webhook |
| SMS not sending | Confirm SMS capabilities are enabled on the phone number |
Billing
| Issue | Resolution |
|---|---|
| Invoices not generating | Verify Stripe keys are set and the billing scheduler is running |
| Catalog sync drift | Use the Resync action on products showing drift or error status |
| Ledger totals incorrect | Run charge reconciliation to repair mirrors and ledger drift |
| Webhook not processing | Check Stripe webhook delivery status in the Stripe Dashboard |
SEO Agent
| Issue | Resolution |
|---|---|
Agent returns none | No executable action available — check action context via the API |
Campaign stuck in running | Worker may have lost the lease — check heartbeat timestamps |
| Blog drafts not appearing | Verify the WordPress connection and website execution are working |
| Keyword ideas not picked up | Check priority and scheduling metadata — future-dated ideas are held until due |
Diagnostic Commands
# Check platform status
GET /status
# Verify a client's integration connections
GET /admin/clients/:clientId
# Check SEO agent runtime state
GET /admin/seo/agents/:agentId/runtime
# Verify Google Ads connection
GET /admin/google-ads/connections/:connectionId
# Test landing page attribution
GET /lp-api/:slug
Getting Support
For issues not covered here:
- Check the audit logs for detailed error context
- Review the relevant agent or integration documentation
- Run the diagnostic commands above and note the output
- Contact the platform team with the error details and relevant log entries
Environment Variables Reference
Key environment variables that affect platform behavior:
| Variable | Purpose |
|---|---|
STRIPE_SECRET_KEY | Stripe API authentication |
STRIPE_WEBHOOK_SECRET | Stripe webhook verification |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | Google OAuth |
GOOGLE_ADS_DEVELOPER_TOKEN | Google Ads API access |
META_SYSTEM_USER_TOKEN | Meta Graph API access |
CF_R2_BUCKET | Client asset storage |
CF_AI_GATEWAY_SLUG | AI model routing |
REDIRECT_URL | Short link base URL |