# Troubleshooting

| Symptom | Likely cause / fix |
|---|---|
| 500 error after upload | `storage/` or `bootstrap/cache/` not writable; missing `.env`/`APP_KEY`; PHP < 8.2. Check `storage/logs/laravel.log`. |
| "No application encryption key" | Run `php artisan key:generate --force` once (never after provider secrets are saved). |
| `Unsupported cipher` / secrets unreadable after restore | `APP_KEY` differs from the one used when data was written – restore the original key. |
| Assets 404 / unstyled | Option B layout: `public/assets` must be inside `public_html/`; `APP_URL` must match the site URL. |
| Cron not running calls | Check the cron command path/PHP version; run `php artisan schedule:run` manually; Admin → Calls shows overdue `queued`. Overlap lock: wait 1 min or clear cache lock `voiceorder:queue`. |
| Calls stay `queued` | Not due yet (client call delay) or cron missing. |
| "No active voice provider" (503) | Activate a provider in Voice API Management. |
| Test connection says "authentication has NOT been verified" | No `test_endpoint` configured – get one from the provider docs; use test call instead. |
| Webhook events show `rejected` | Wrong webhook secret/header/prefix; the proxy altered the body; for timestamp setups check clock skew. |
| Webhook events show `unmatched` | `webhook_map` doesn't point at the real fields, or the provider doesn't echo our reference/call id. See TZSMM doc. |
| Call `awaiting_reconciliation` | Dispatch timed out. Check the provider dashboard, then Admin → Call → Resolve (placed / not placed). |
| Verification emails not arriving | `MAIL_*` wrong or SPF/DKIM missing; check `storage/logs`. Free credits are only granted after verification. |
| Plugin: "ownership verification failed" | REST API blocked (security plugin/firewall/auth-required), plain permalinks (the SaaS retries via `?rest_route=`), site not on HTTPS, or the server can't reach itself. |
| Plugin: orders not updating after calls | See WP → VoiceOrder → Logs for `rejected_push` (clock skew >5 min or wrong callback secret → paste new credentials). The SaaS retries pushes with backoff. |
| Plugin: "Connection refused / approval required" | Website slot used; request approval from the connect screen. |
| Insufficient balance | Recharge in Wallet; staff approve manual payments in Admin → Recharges. |
| Free credits missing | Email not verified, or withheld by the per-IP cap (staff are notified and can grant manually). |