# Troubleshooting

## Overview

This page lists the most common install-time and runtime issues, each as problem → cause → fix. Most install problems come down to file permissions, PHP extensions, or the database; most runtime problems come down to the Node helper service or its shared secret.

> First place to look: the log file at `storage/logs/laravel.log` usually contains the exact error. For the helper service, check its console output (or `pm2 logs` if you run it under PM2).

## Storage / Permission Errors

Problem: The installer's Requirements step shows a red cross on `storage`, `bootstrap/cache`, or `.env writable` — or after install you see "failed to open stream: Permission denied" or "The stream or file could not be opened".

Cause: The web-server user cannot write to the folders Laravel needs, or cannot write the `.env` file the installer must create.

Fix: Make the two writable folders owned by the web-server user with `775` permissions, and ensure the project root / `.env` is writable:

    chown -R www-data:www-data storage bootstrap/cache
    chmod -R 775 storage bootstrap/cache

On cPanel/shared hosting, use the File Manager to set `storage` and `bootstrap/cache` (and their subfolders) to `755` or `775`. Then reload the Requirements page — the check re-runs automatically, no need to restart the wizard.

## Requirements Step Won't Pass

Problem: A PHP extension shows a cross, or the PDO panel does not list `mysql`, and the Continue button stays disabled.

Cause: A required PHP extension (commonly `gd`, `zip`, or `pdo_mysql`) is not enabled for the active PHP version.

Fix:

- cPanel: "Select PHP Version" → Extensions tab → tick the missing extension.
- Plesk: "PHP Settings" → enable the extension.
- VPS: install the package, e.g. `apt install php8.2-gd php8.2-zip php8.2-mysql`, then restart PHP-FPM.

Confirm the web PHP version matches your CLI PHP version — some hosts run different builds for each. Reload the page after enabling.

## Database Connection Fails

Problem: On the Database step, Test connection returns a red error such as "Access denied", "Unknown database", or "Connection refused".

Cause: Wrong host, a database that does not exist, or a user without privileges on it.

Fix:

- Access denied: Verify the username/password and that the user is granted privileges on this specific database.
- Unknown database: Create the empty database first, then re-test.
- Connection refused / can't connect: Try `127.0.0.1` instead of `localhost` (or vice versa), confirm the port (default `3306`), and make sure MySQL is running.

> Tip: The test uses a live PDO connection with the exact values you typed, so the error message it shows is the real database error — read it literally.

## Forms Return 419 / Page Expired During Install

Problem: Submitting a wizard step returns a "419 Page Expired" error.

Cause: The application key could not be written, or the install session cookie was lost — usually because `.env` (or the project root) was not writable when the wizard first loaded.

Fix: Make the project root and `.env` writable (see Storage / Permission Errors), then revisit `/install` from the start. WaDesk auto-generates a valid `APP_KEY` on first load when the file is writable, which is what signs the CSRF tokens.

## Blank White Page After Install (500 Error)

Problem: The site loads a completely blank page, or a generic 500, after installation.

Cause: A server-side error — commonly stale cached config pointing at the wrong values, lingering permission issues, or a missing PHP extension on the web (FPM) PHP build.

Fix:

1. Open `storage/logs/laravel.log` and read the latest entry — it names the exact problem.
2. Clear cached config and views:

    php artisan optimize:clear

Re-check folder permissions and confirm the web-facing PHP version has all required extensions. The installer's last step already clears caches, so a blank page usually means a permission or extension issue rather than cache.

## Site Keeps Redirecting to /install (or Won't Leave It)

Problem: Every page bounces back to `/install` even though you finished — or, conversely, you cannot reach `/install` at all.

Cause: WaDesk treats the file `storage/installed` as the "installed" flag. If it is missing, the app assumes a fresh install and redirects to the wizard; if it exists, the wizard redirects back to the homepage.

Fix:

- Stuck on /install after finishing: Confirm the final install step succeeded and that `storage/installed` exists and is readable. If the last step failed to write it (permissions), fix permissions and re-run the final step.
- Want to reinstall from scratch: Only then delete `storage/installed` and use an empty database. Never do this on a live install with real data.

## Helper Service Offline / Sends Not Going Out

Problem: Unofficial API messages do not send, devices show as disconnected, or status updates never arrive.

Cause: The Node helper service is not running, WaDesk does not know its URL, or the shared secret does not match.

Fix:

1. Confirm the service is alive: `pm2 status` (or start it with `node index.js` from the `node/` folder).
2. Confirm the service URL is set in the admin panel under Settings → Providers ("Default Node server URL"), e.g. `http://localhost:8888`, and that the port matches `PORT` in `node/.env`.
3. Confirm `NODE_WEBHOOK_TOKEN` is identical in `node/.env` and WaDesk's own `.env`. A mismatch makes WaDesk reject the service's updates, so sends and status updates silently fail.
4. If you see CORS errors in the browser console, confirm your domain is in the service's allowed-origins list.

> It must stay up: The helper service also runs the scheduler for bulk campaigns, scheduled, and recurring sends on the Unofficial API. If it stops, those pause until it restarts — always run it under PM2, systemd, or Supervisor in production.

## QR Code Won't Generate

Problem: On the device connect screen, clicking Generate QR shows nothing, spins forever, or errors.

Cause: WaDesk cannot reach the helper service to start a session, or the service cannot connect to WhatsApp.

Fix:

- Verify the service is running and reachable at the configured URL (open `http://your-service-host:8888` from the server to confirm).
- Check the service logs for connection errors while it tries to connect to WhatsApp.
- Make sure the phone number entered is correct and not already paired in another session.
- If a QR appears but expires before you scan, click Generate again — pairing QRs are short-lived by design. The page refreshes automatically.

## Scheduled / Bulk Sends Not Running

Problem: Scheduled campaigns or recurring messages on the Unofficial API do not fire at their set time.

Cause: This scheduling is driven by the Node helper service's own scheduler — not a background worker or cron. If the service is down or was restarted, pending schedules pause.

Fix:

- Keep the helper service running continuously under a process manager (see Helper Service Offline).
- After restarting it, the service reloads active campaign and scheduled-message timings on startup — give it a moment to catch up.
- In-app housekeeping (inbox SLA, snooze wake-ups) runs while an operator has the Team Inbox open; it does not need a cron. On a VPS you may optionally add a cron for stricter timing.

## Missing Styles / Broken Assets

Problem: Pages load unstyled, or the browser console shows 404s for files under `build/`.

Cause: The compiled front-end assets (Vite build) are missing — this happens with a source build that was never compiled, or after changing front-end files.

Fix: Build the assets once:

    npm install
    npm run build

If you uploaded a ready-to-use package, the `public/build/` directory is already included — in that case re-upload it intact rather than rebuilding. Also confirm `APP_URL` in `.env` matches the URL you are actually visiting, and that `public/` is your document root.

## Cloud API / Twilio Webhooks Not Arriving

Problem: Inbound messages or status updates from the Cloud API or Twilio channels never reach WaDesk.

Cause: The webhook URL is not reachable over HTTPS, or the verify token does not match what you set in the provider dashboard.

Fix:

- Ensure your site is served over HTTPS with a valid certificate — Meta and Twilio only deliver to HTTPS endpoints.
- Point the provider's webhook at WaDesk's inbound endpoint (`/webhooks/whatsapp/inbound`) and use the same verify token you configured in the admin Providers settings.
- Confirm `APP_URL` is correct so generated callback URLs point at your real domain.

## Still Stuck?

If a problem persists after the fixes above:

- Read the most recent lines of `storage/logs/laravel.log` — it almost always names the exact failure.
- Temporarily set `APP_DEBUG=true` in `.env` to see the full error in the browser, then run `php artisan optimize:clear`. Set it back to `false` for production afterwards.
- Check the Node helper service logs for any Unofficial API issue.

> Security reminder: Never leave `APP_DEBUG=true` on a live, public install — it can expose configuration details. Re-disable it once you have captured the error.