Troubleshooting FOSSBilling Issues

Common Problems and Solutions

When troubleshooting, you will usually need the FOSSBilling log files. Their location is covered in the FAQ.

HTTP Error 404 / Can only access client dashboard

Subfolder installations

FOSSBilling does not support subfolder installations (for example, https://example.com/billing). Use a dedicated subdomain such as https://billing.example.com instead.

Support for subfolder installations was deprecated in FOSSBilling 0.4.2. They are not currently supported. Install FOSSBilling in the document root for its own domain or subdomain instead.

Apache, LiteSpeed, or OpenLiteSpeed

If you are using Apache, LiteSpeed, or OpenLiteSpeed and receive HTTP 404 errors in parts of FOSSBilling, check the following:

• Ensure that you have mod_rewrite installed and enabled.
• Verify there is a valid .htaccess file in the same directory as the FOSSBilling index.php file.
• If you do have a valid .htaccess file, verify that it matches the default FOSSBilling one.
• If you are using OpenLiteSpeed, restart the service so the updated .htaccess file is loaded.
• If you have checked all of the above, restart the web server. Some configuration changes are not applied until the service reloads.

Apache

• Ensure that AllowOverride All is enabled.
• See this Stack Overflow answer for background if you are not sure where to configure it.

NGINX

• Verify that you loaded the recommended NGINX configuration.

Cloudflare specific issues

Some Cloudflare features can interfere with FOSSBilling. Here are the most common ones to check.

Auto Minify

• Enabling Cloudflare's "Auto Minify" feature can break integrity checks in the admin panel. When that happens, JavaScript and CSS files stop loading and the admin panel may become unusable. A browser error usually looks like this: None of the "sha384" hashes in the integrity attribute match the content of the subresource.
• Disable "Auto Minify" to fix the issue.

Permission issues

If you are seeing permission-related errors around config.php, the cache, uploads, or updates, these checks usually help.

File and folder permissions

• If your control panel has a "fix permissions" button, try that first.
• Verify files and folders for your website have the correct permissions applied. Usually 755 is correct for folders and 644 for most PHP files, but security-sensitive files such as config.php may require stricter permissions (for example 600 or 640) depending on your server setup.
  • From within your terminal and under the document root, you can manually apply the correct permissions by using the following commands:
    • find . -type d -exec chmod 755 {} \; to apply 755 to all folders.
    • find . -type f -exec chmod 644 {} \; to apply 644 to all files.

File ownership

If the wrong owner is assigned to the files, correct permission bits alone will not fix the problem. You can check the effective PHP user with these steps:

• Create a new PHP file and place the following contents inside of it: <?php var_dump(get_current_user());?>
• Open the PHP file in your browser. It will show the user PHP runs as, which tells you which user or group should own the relevant files.

RHEL Linux (and derivatives)

If you are using a RHEL-derived Linux distribution such as RHEL, CentOS, Rocky Linux, or AlmaLinux, SELinux may still block file creation even when Unix permissions look correct. Try the following:

• Configure SELinux to allow PHP (Recommended)
  1. Ensure you have the policycoreutils-python package installed.
  2. Set the proper context for the document root
     • Note: Please check the paths in the below code snippets before executing them. Your actual paths may differ.
     1. semanage fcontext -a -t httpd_sys_content_t '/var/www/html(/.*)?'
     2. restorecon -Rv /var/www/html
  3. Configure SELinux rules.
     1. setsebool -P httpd_can_network_connect on
     2. setsebool -P httpd_can_sendmail on
     3. Install the selinux-policy-devel package
     4. setsebool -P httpd_can_network_connect_db on
  4. Restart the server
• Disable SELinux (Discouraged)
  • Edit /etc/selinux/config
  • Change SELINUX=enforcing to SELINUX=disabled and save the file
  • Reboot the server

Unknown "encore_entry_link_tags" function.

This error usually appears when FOSSBilling is installed under a subfolder such as example.com/billing. Subfolder installations are not supported right now. Install FOSSBilling on a dedicated subdomain such as billing.example.com instead.

Errors after updating

If FOSSBilling starts failing after an update, work through these steps:

1. Review the changelog for any breaking changes or for any manual actions required.
2. Try the fallback patcher by visiting https://example.com/run-patcher to make sure database and configuration updates finished cleanly.
   • If you need the fallback patcher, there is often an underlying permissions issue interrupting the normal update flow.
3. If you're still experiencing issues, you can ask for further assistance via our Discord, or with a bug report.

Issues with cron

If you see a warning like this in the FOSSBilling dashboard, cron has not run for at least 15 minutes. That is a real problem because many core tasks depend on it.

1. Check the FOSSBilling logs for any PHP or application errors.
2. Confirm that cron is configured to run every five minutes. FOSSBilling shows a crontab example with the correct path for your installation under the cron settings (/admin/extension/settings/cron).
3. If you're using a control panel with multiple users, log into your user account via the CLI and enter php -v to see what the default PHP version is under your account. If it's less than FOSSBilling's minimum PHP version, follow the below steps to correct it.

An incorrect PHP version is being used

Because cron runs as a server command, it is not tied to the PHP version configured for a specific site. Control panels often default to an older system PHP binary, which can make the cron job fail if that version is below FOSSBilling's minimum requirement.

These steps may help you resolve this issue:

1. If your control panel provides a PHP selector for cron, choose a version that meets FOSSBilling's requirements.
2. Try specifying a different PHP binary in the cron command, for example php8.2 or /usr/bin/php8.2 instead of just php.
3. Remove unsupported PHP versions if they keep being selected by default.
4. Ask your hosting or control-panel provider how to set a different PHP version for cron jobs.
5. As a last resort, use the cron API endpoint with wget or an external cron service.
   • Be aware that cron can run for a while. Triggering it over HTTP is more likely to hit timeout limits than running it locally.

Administrator account login issues

• Verify that you are using the administrator login page. The client and admin areas are separate, and the default admin prefix is /admin (https://example.com/admin).
• Manually reset your admin password.

curl_multi_exec errors

If you are seeing errors involving curl_multi_exec, your control panel or host has probably disabled that PHP function. You will need to re-enable it before FOSSBilling can work correctly on that server.