Desorix

Appearance

Troubleshooting ​

Installer ​

  • "This database already has Desorix tables": the installer never deletes data. Use a new, empty database, or drop all tables of this one in phpMyAdmin (select all → Drop) and try again. If your first install attempt stopped half-way, enter exactly the same database details again: that install can continue.
  • "The username or password was refused" / "no access to the database": in cPanel → MySQL Databases, check the user is added to the database with ALL PRIVILEGES. The database and user names include your account prefix.
  • ".env cannot be created": the desorix folder must be writable (755). In File Manager, select the folder → Permissions.
  • A step shows "This step failed": the message says why. Fix it and click Try again; finished steps aren't repeated.
  • Every address shows the hosting's own "404 Not Found" page (not a Desorix page), even right after uploading: the web server can't enter the desorix folder or a folder above it. In File Manager, set the folder that holds desorix, desorix itself and desorix/public to 755 (select the folder → Permissions). The release zip already sets 755; this happens when a folder was created another way, for example by cPanel's Git Version Control, which uses 700. Also check that the domain's document root ends in desorix/public.
  • Every page opens the installer after installing: storage/app/installed.json is missing, or storage/ isn't writable.

Updates ​

  • "Could not check for updates": the license server couldn't be reached. Desorix keeps working, and you can still Upload the zip. Check that your host allows outgoing HTTPS.
  • "Activate your purchase code…": one-click updates need an active code (Administration → License). Uploading the zip doesn't.
  • "The release signature is not valid" / "A file was changed after signing": the zip was altered or damaged. Download it again from CodeCanyon, and upload desorix-x.y.z.zip, not the CodeCanyon package or a re-zipped folder.
  • The upload fails straight away: the zip is larger than upload_max_filesize. Put it in storage/app/updates/ with File Manager and click Use this file.
  • "Desorix can't write to …": folders must be writable by PHP (755, owned by your cPanel user).
  • "Waiting for the server to load the new files…" doesn't end: restart PHP (cPanel → Select PHP Version → choose the same version → save), then reload.
  • The site shows "Service unavailable" after an update: open /admin/updates/finish and click Finish update. If you can't reach it, delete storage/framework/down with File Manager.
  • Something is wrong after updating: Administration → Updates → Roll back puts the previous files back.

Modules ​

  • A module page stays blank: the module's built pages are missing (modules/{Name}/dist/module.js), or it didn't load in time. Administration → Modules shows a warning; download the module again. The browser console names the module.
  • A module disappeared from the sidebar after an update: reload once. The module list is rebuilt on the first request after an update.

Scheduler not running ​

Admin → System shows Not running when the cron job hasn't run in the last 3 minutes.

  1. Check that the cron job exists in cPanel → Cron Jobs and runs every minute.
  2. Copy the exact line shown on the System page. It uses the correct paths for your server.
  3. If your host's default php is older than 8.3, cron fails silently. Use the full path shown on the System page, e.g. /opt/alt/php83/usr/bin/php.
  4. To see the error, temporarily replace >> /dev/null 2>&1 with >> /home/account/desorix/storage/logs/cron.log 2>&1 and check that file after a minute.

Background jobs stay "queued" ​

Jobs are processed by the scheduler every minute on shared hosting. If jobs pile up:

  • Make sure the scheduler is running (above).
  • Check that proc_open isn't disabled (Admin → System → PHP functions).
  • Failed jobs are listed as Failed on the System page. Details are in storage/logs/laravel-*.log.
  • Oldest waiting on the System page shows how long the next job has waited, and Waiting lists the jobs by type. Over a few minutes while the scheduler runs usually means a slow job is holding the single worker. A common cause is email with an unreachable mail server: each queued email waits for the connection to time out. Set MAIL_MAILER=log until email is configured.

"500 Server Error" right after installing or updating ​

  • storage/ and bootstrap/cache/ must be writable by PHP.
  • Check storage/logs/laravel-*.log for the real error.
  • If you changed .env, clear the cached configuration. The updater does this automatically; from a terminal, run php artisan optimize:clear.

Blank page or unstyled page ​

The public/build folder is missing or incomplete. Upload it again from the release zip. It is never built on the server.

WhatsApp: real messages don't arrive ​

Work through these in order:

  1. Is the Meta app Live? Apps in Development mode only receive test events from the dashboard. See Publish your Meta app.
  2. Does the account page say Webhook: Verified? If not, the Callback URL or Verify token in Meta doesn't match. Copy both again from wizard step 2.
  3. Run Test connection. It subscribes your WhatsApp Business Account to the app; without that subscription Meta sends nothing.
  4. Is the number added in step 4? Messages for numbers that aren't added to a workspace are ignored.
  5. Is there a red warning about the signature? The App Secret in Desorix doesn't match the app. Paste it again (App settings → Basic).
  6. Is the scheduler running? Webhooks are processed immediately, but retries and media downloads need the cron job.

WhatsApp: statuses stay "pending" ​

"pending" means Meta accepted the message but no status webhook has arrived yet. Check the webhook steps above. Statuses usually arrive within seconds.

WhatsApp: attachments show "failed" ​

Media is downloaded by a background job within a minute. "failed" usually means the access token expired (replace it and run Test connection) or the file was larger than 100 MB.

Inbox: new messages take a few seconds to appear ​

That's normal on shared hosting: the inbox checks for changes every few seconds (Administration → Settings → Inbox polling interval). For instant updates on a VPS, see Realtime.

Inbox: "The 24-hour reply window is closed" ​

WhatsApp only allows free-form replies within 24 hours of the customer's last message. Send an approved template instead. When the customer answers, the window opens again.

Inbox: attachments fail to send ​

  • Photos: up to 5 MB. Other files: up to 16 MB. Your host's PHP upload_max_filesize and post_max_size may be lower; raise them in cPanel → Select PHP Version → Options.
  • Only file types WhatsApp accepts can be sent: JPEG/PNG, MP4/3GP, common audio, PDF, Office documents and plain text.

Import: "not a valid phone number" ​

Numbers need a country code (+254…), or pick a Default country in the import options for numbers written locally (0712…). Download Rows with errors, fix them and import that file again. Rows that already imported are updated, not duplicated.

Template rejected ​

Open the template to see Meta's reason. Common causes are variables at the start or end of the body, a promotional text in the utility category, or missing example values. Edit it and submit again.

Broadcast paused ​

The page shows why:

  • Meta rated the number's quality as low: check WhatsApp Manager, wait for it to recover, then Resume.
  • The template was paused or disabled by Meta.
  • The header file couldn't be uploaded.

Broadcast sends slowly ​

On shared hosting a broadcast sends in batches once a minute, a few messages per second, so 10,000 recipients takes about an hour. That is expected. A VPS with a queue worker sends faster.

Chatbot: the bot doesn't answer ​

Check, in order:

  1. The flow is published and Active (Chatbot flows list). Rules that point to a switched-off flow are skipped.
  2. The rule is Active, applies to that number, and its cooldown has passed for that conversation.
  3. The conversation isn't paused: after an agent replies, the bot stays quiet (24 hours by default). The inbox's Chatbot section shows Paused until… with Hand back to the bot.
  4. The message was just the keyword when the match is The whole message is the keyword. Use contains for keywords inside sentences.
  5. The message wasn't a consent keyword. STOP and START never trigger rules.

The flow's Runs page shows every run and why it ended.

Chatbot: a flow stops after a wait ​

A Wait step only continues when the scheduler runs desorix:run-flows every minute (see "Scheduler not running"). If the run ended as 24-hour window closed, the wait was longer than WhatsApp's service window; send an Approved template after long waits.

Chatbot: webhook step always follows "Error" ​

The Runs page and step log show the reason. Private or local address means the URL points to your own server or network (set DESORIX_ALLOW_PRIVATE_WEBHOOKS=true if that's intended). Otherwise check that the service answers with a 2xx status within 10 seconds and doesn't redirect.

AI: auto-reply doesn't answer ​

  1. AI → Auto-reply is on, the number is ticked (or none are), and the business description is filled in.
  2. A key is listed and Test shows Works (or the platform has a key).
  3. No automation rule or flow answered first, and the conversation isn't paused after an agent reply or a handoff.
  4. The monthly spend limit isn't reached (a banner on the AI page), and the reply limit for that conversation isn't used up.
  5. The inbox thread shows a grey "handed this conversation to the team" line when the AI chose not to answer, with the reason.

AI: documents stay "Queued" ​

Indexing runs on the queue: check that cron runs schedule:run every minute (see "Scheduler not running"), then see "Background jobs stay queued" above. "No text was found" means a scanned PDF; paste the text instead.

Cost alerts don't arrive ​

Check the alert's Last sent line on the Costs page. If it was sent but nothing arrived, email isn't set up: with MAIL_MAILER=log the emails are written to storage/logs/laravel.log. Configure SMTP under your .env mail settings.

Emails don't arrive ​

Check the MAIL_* settings in .env. Most shared hosts block outgoing SMTP ports 25 and 465 to external servers, so use port 587 with your provider's credentials.