Get Started

Troubleshooting

The 10 most common Deskuss issues and how to fix them. If something is broken, start here.

1. Permalinks 404 on /deskuss/

Symptom: Visiting /deskuss/ shows the WordPress 404 page.

Cause: Permalinks are set to "Plain", the rewrite rules haven't been flushed, or the NGINX rewrite is missing.

Fix:

  1. Go to Settings → Permalinks in WordPress
  2. Set to anything except "Plain" (e.g., "Post name")
  3. Click Save Changes
  4. On Apache, confirm .htaccess is writable
  5. On NGINX, see the rewrite rule in System Requirements → NGINX

2. Cron never fires (overdue tickets not flagged, mail not polled)

Symptom: Tickets never become "Overdue". POP/IMAP fetch never runs. Reports show stale data.

Cause: WP-Cron only fires on page loads, so low-traffic sites never trigger it. Some hosts disable it entirely.

Fix: Set up a real system cron that hits wp-cron.php every 5 minutes:

*/5 * * * * curl -s https://example.com/wp-cron.php > /dev/null 2>&1

3. SMTP auth fails / "could not instantiate mail function"

Symptom: Outgoing notifications never arrive. System log shows a "mailer" error.

Cause: WordPress's default mail() is unreliable, or your SMTP credentials are wrong.

Fix:

  1. Configure a real SMTP account under Emails → Email Addresses
  2. For Gmail / Workspace, use an App Password (regular passwords no longer work)
  3. Test by visiting Emails → Test Outgoing Email
  4. Check the system log for the actual error

4. Email piping loop (your own notifications become tickets)

Symptom: Your own notification emails get ingested back as tickets. Queue fills with duplicates of your own messages.

Cause: The "From" address on outgoing emails matches the address that's being fetched or piped. The reply triggers another outgoing email, which triggers another ingestion…

Fix:

  1. Set a different From address for outgoing mail than for incoming (e.g., outgoing from support@, incoming to tickets@)
  2. Add the From address to a Reject filter with reason "self-loop"
  3. Empty the ticket queue and start fresh

5. POP/IMAP fetch not running

Symptom: Customer emails to tickets@ never become tickets.

Fix:

  1. Verify the email account is configured in Emails → Email Addresses with correct host/port/TLS
  2. Test by clicking Save on the email account (Deskuss runs a connection test)
  3. Check that cron is actually firing (see issue 2)
  4. Some hosts (Gmail, Outlook.com) require app-specific passwords and IMAP explicitly enabled
  5. Some managed hosts block outgoing port 993/995 — check the firewall

6. Internal Server Error on staff login

Symptom: Submitting the staff login form returns 500.

Fix:

  1. Check wp-content/debug.log for the actual error
  2. Most common cause: a permission check is failing because the user is missing the deskuss_staff capability. Re-run the role sync from Settings → General → Users
  3. Disable all other plugins temporarily to rule out a conflict
  4. Switch to a default theme (Twenty Twenty-Four) to rule out a theme conflict

7. WP admin redirect loop with support_client role

Symptom: A user assigned the support_client role hits a redirect loop on /wp-admin/.

Cause: This is intentional — Deskuss redirects clients to the portal. If you need to give a specific client temporary admin access, promote them to a higher role (administrator) for the duration of the work.

8. License key not accepted

Symptom: Saving your license key in Deskuss → License shows an "invalid" message.

Fix:

9. Auto-responder never arrives

Symptom: Customer opens a ticket but never receives the confirmation / auth-link email.

Fix:

10. Email loop is back (your notifications become tickets)

See issue 4. The signature mismatch between your From address and the polled mailbox is the only way this happens. Use a different address for each direction, or add a Reject filter.

Where to Find the System Log

Most issues leave a trace in the system log. Find it at Deskuss → System → Logs. The log is filterable by level (Debug, Info, Warning, Error), time range, and source.

Enabling Debug Logging

For deeper investigation, enable debug mode in Settings → System → Log Level:

  1. Set Log Level to "Debug"
  2. Reproduce the issue
  3. Set the log level back to "Warning" or "Error" — debug logs grow fast
  4. Pull the relevant entries from the system log and share them with support

Getting Help

When the docs and the system log don't reveal the issue, here's the fastest path to a fix:

  1. WordPress.org support forum — best for free-plugin users; community + Deskuss team members monitor threads
  2. Premium support — included with paid plans; opens a private ticket at deskuss.deskuss.com
  3. Security disclosures — email security@deskuss.net (do not post publicly)

When you reach out, please include: WordPress version, PHP version, Deskuss version, list of active plugins, the system log entries around the issue, and reproduction steps. The more context, the faster the fix.