FAQ & troubleshooting

Setup

npx prisma db push fails / can't reach the database Create the MySQL database first, then confirm DATABASE_URL — it is one connection string, mysql://user:password@host:3306/dbname. Once it connects, run npm run db:seed.

@prisma/client did not initialize yet Run npm run db:generate (or npm run build, which generates first). This happens after editing prisma/schema.prisma or a fresh npm install.

The frontend looks unstyled or the build fails Run npm install, then npm run build (production) or npm run dev (development). After deploying changes, always rebuild.

I changed .env but nothing changed Next.js reads the environment at boot. Restart npm run dev / npm start — and restart npm run worker too, it loads .env on start.

Calls

Campaigns launch but no calls are placed The dialer only runs when something POSTs the cron endpoint. Confirm the scheduler is alive:

npm run worker                                            # bundled scheduler

curl -X POST -H "X-Cron-Secret: $CRON_SECRET" \
     https://your-domain.com/api/cron/heartbeat           # should return 200

A 401 means CRON_SECRET (or AUTH_SECRET) does not match what the caller sends. See Deployment.

Calls fail immediately Check, in order: Twilio credentials set (Telephony); the customer has credits (Billing & Credits); the tenant is KYC-verified and within plan limits; an ElevenLabs key is added and healthy (Voice & AI).

Recordings / transcripts don't appear Twilio calls back to your TWILIO_*_CALLBACK_URL. In production this must be a public HTTPS URL; locally use a tunnel (e.g. ngrok). Recordings can also be re-pulled from the Calls page (Sync recordings).

Voice preview says "unavailable" Add an ElevenLabs key in /admin/elevenlabs-keys, run Health check, then Sync voices — placeholder/stale voices are retired on sync.

Billing & plans

Customer can't buy a number or launch a campaign These actions require KYC verified status. The customer uploads documents at /app/verification; an admin approves them at the KYC review screen. They also require available credits and headroom in the plan limits.

A feature (Messaging / API / SIP / Team roles) is hidden Those are plan-gated. Enable the corresponding feature flag on the customer's plan in /admin/plans. See Roles & permissions and the add-on pages.

Localization

Switching currency doesn't change prices Money on catalog/estimate pages converts to the display currency; historical charges keep their original currency. Ensure the currency's exchange_rate is correct (USD-per-unit) in /admin/currencies. See Localization.

Switching language shows English on some pages Core UI (navigation, common controls, admin) is translated; deep page-body strings fall back to English by design.

Admin

Admin panel looks broken after logging in The admin panel runs on its own session cookie (cm_admin, backed by admin_users), separate from customer accounts (cm_session). Sign in at /admin/login, not /login.

Where did the Templates page go? Email templates were merged into Admin → Email System. The old /admin/templates URL redirects there.

Demo mode

All save/delete buttons return "changes are disabled"APP_DEMO_MODE=true blocks create/update/delete in both panels. Set it to false to allow writes.

Still stuck? Check the Next.js server output (npm start / your PM2 or systemd logs), the npm run worker output, and your provider dashboards (Twilio, ElevenLabs, OpenAI) for the underlying error.