Troubleshooting

The Merge and Link features were introduced in osTicket 1.17. If you don’t see them, make sure you’re running osTicket 1.17 or later.

If you are on 1.17+ and they’re still missing, check that the features are enabled under Admin Panel → Settings → Tickets → Merge and Link.

osTicket Awesome includes a built-in diagnostic tool. Press Shift+O on any page to instantly switch between osTicket Awesome and vanilla osTicket. If the problem persists in vanilla osTicket mode, it’s an upstream core issue, not an osTicket Awesome issue.

This is especially useful when posting on the osTicket community forums; use vanilla osTicket screenshots to avoid “we don’t support modified installs” deflection.

Don’t panic. The most common cause is a failed file upload during an upgrade. Here’s what to do:

1. Re-upload all osTicket Awesome files via FTP or your file manager, making sure to overwrite everything.
2. If you have a database backup, restore it.
3. If you don’t have a backup and the installer screen appears, do not run it. Your data is likely still intact; the files just need to be in place.

If the issue happened during an upgrade and you need to roll back, keep in mind that schema migrations run automatically on first page load after file replacement. If the new version changed the database schema, simply putting old files back may not be enough; you’ll need the database backup too.

This generic error usually means a PHP error is happening behind the scenes. To find the real error:

1. Check your server’s PHP error log (usually in /var/log/ or your hosting control panel).
2. Temporarily enable display_errors in php.ini or .htaccess to see the actual error message.
3. Common causes: wrong PHP version, missing mysqli extension, incorrect database credentials in include/ost-config.php.

For most Linux/Apache setups:

• Folders: 755 (drwxr-xr-x)
• Files: 644 (-rw-r–r–)
• include/ost-config.php: 644 (some guides suggest 600)
• uploads/ directory: writable by the web server

On Ubuntu/Debian, the web server user is usually www-data. On CentOS/RHEL, it’s apache or nobody.

This is almost always a file permissions issue. The web server needs write access to the uploads directory.

chown -R www-data:www-data /path/to/osticket/uploads/
chmod -R 755 /path/to/osticket/uploads/

Replace www-data with your web server’s user if different. Also check that PHP’s upload_max_filesize and post_max_size are large enough for your image.

A 500 error means something went wrong on the server side. Check these in order:

1. PHP error log — the real error message is almost always here.
2. .htaccess — a malformed rewrite rule or unsupported directive will cause a 500. Try temporarily renaming .htaccess to see if the site loads.
3. PHP version — make sure your hosting is running PHP 8.2 – 8.4.
4. File permissions — overly restrictive permissions (e.g. 600 on directories) can trigger this.

This usually means the web server user doesn’t own or can’t read the osTicket files.

chown -R www-data:www-data /path/to/osticket/

On shared hosting, you may not have shell access. Use your hosting control panel’s File Manager to check and fix permissions, or contact your hosting provider.

If email piping was working before an upgrade and stopped, you’ll need to reconfigure it. The piping script path may have changed. Check:

1. That the pipe script (api/pipe.php) is still present and executable.
2. That your mail server’s alias or forward rule points to the correct path.
3. That PHP CLI is available and working (test with php -v from the command line).

Email piping is an alternative to IMAP/POP fetching. Most users are better served by osTicket’s built-in email fetching, which doesn’t require piping configuration.

Usually a browser cache issue. Clear your browser cache first.

If that doesn’t help, check for PHP errors. A blank page often means PHP is fatally erroring but display_errors is off. Check your error log or temporarily enable error display.

Missing elements (like icons or buttons) can also mean incomplete file uploads during an upgrade. Re-upload all osTicket Awesome files.

This is typically caused by one of these:

1. Session issues — PHP sessions aren’t being stored. Check that the session save path is writable and that session.save_handler is set to files in your PHP config.
2. Cookie domain mismatch — if your helpdesk URL recently changed (e.g. added www or switched to HTTPS), the cookie domain in include/ost-config.php may not match.
3. HTTPS redirect — if you recently enabled HTTPS, make sure your HELPDESK_URL and ROOT_PATH in ost-config.php use https://.