Troubleshooting the Database
If you encounter errors or issues while working with the database for your WHMCS installation, see the sections below to start troubleshooting and resolve the issue.
- For more information, see Database Requirements.
- For general steps to troubleshoot problems in WHMCS, see Start Troubleshooting.
General Issues
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
TypeError: Argument 1 passed to Illuminate\Database\Connection::prepared() must be an instance of PDOStatement, bool given or TypeError: Argument 1 passed to WHMCS\Database\MysqlCompat::setLastStatement() must be an instance of PDOStatement or null, bool | Thesystem is logging a large amount of data to the MySQL® database or the wait_timeout and interactive_timeout variables in the MySQL server configuration are too low to complete the request. | Argument PDOStatement Errors |
SQLSTATE[42S02]: Base table or view not found: 1146 Table 'table_whmcs7.tbldomainpricing_premium' doesn't exist or Unable to complete incremental updates | A required table is missing from the WHMCS MySQL® database. | Base Table or View Not Found Errors |
SQLSTATE[23000]: Integrity constraint violation: 1048 Column 'group_id' cannot be null (SQL: insert into tblproducts_slugs (group_id, group_slug, slug, active, product_id, updated_at, created_at) values (?, ?, , 1, 1, 2021-09-30 10:24:30, 2021-09-30 10:24:30)) | There are orphaned products in the database (products which are not in a valid product group). | Column group_id Null Errors |
Unable to complete incremental updates | The MySQL® user has insufficient privileges. | Command Denied Errors |
Could not connect to database | The cron.php script cannot access your MySQL® database. | Could Not Connect Errors |
| During the daily automation cron run, the script takes a long time to complete, especially during the Executing System Queue step. | Processing times have increased due to the size of your WHMCS database. | Cron System Queue Timeout |
InvalidArgumentException: Dataset must be an array in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/TableQuery.php:0 Stack trace: #0 /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/TableModel.php(0): WHMCS\TableQuery->setData(NULL) | The $mysql_charset value is incorrect in the configuration.php file. | Dataset Must Be Array Errors |
Oops! ERROR: WHMCS\Exception\InvalidDomain: The domain is invalid. in /path/to/whmcs/vendor/whmcs/whmcs-foundation/lib/Domains/Idna.php:0 | The tbldomains.domain field in your MySQL® database contains an invalid character. | Domain Management Oops! Errors |
Down for Maintenance (Err2) | There is a mismatch between the database version and WHMCS version or PHP version. | Down for Maintenance Errors |
PDOException: SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '0' for key 'PRIMARY' in /path/to/whmcs/vendor/illuminate/database/Connection.php | The primary key and auto_increment attributes are absent from one or more tables in the WHMCS database. | Duplicate Entry Errors |
Oops! Something went wrong and we couldn't process your request. or SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry '1' for key 'tblconfiguration.PRIMARY' | You have initiated the installation process twice simultaneously. | Duplicate tblconfiguration Errors |
Field xxx doesn't have a default value | You attempted to install WHMCS with MySQL Strict Mode enabled. | Field Default Value Errors |
MySQL server has gone away | The MySQL® server is closing the connection that WHMCS is using for the current task. | MySQL Server Gone Away Errors |
Order Not Found...Exiting... | WHMCS cannot write to the MySQL® database. | Order Not Found Errors |
Error: SQLSTATE[HY000]: General error: 3988 Conversion from collation utf8mb3_unicode_ci into latin1_swedish_ci impossible for parameter (SQL: insert into tblticketmaillog... | MySQL® cannot convert the table in the error message into the indicated character set. | POP3 General Error 3988 Errors |
Critical Error - Unable to connect to the database | The system cannot connect to your database. | Unable to Connect Errors |
Database Backups
For more information, see Database Backups.
You may encounter the following common issues:
| Error or Issue | Cause | Next Steps |
(S)FTP Backup - Uploading Failed | The connection to the FTP server succeeded but the system could not navigate to the destination directory or did not have write permissions. | (S)FTP Backup Upload Errors |
(S)FTP: Unable to open for writing | WHMCS cannot open a test file in the PHP system directory. | (S)FTP Unable to Open Errors |
(S)FTP: Unable to write to temp file | WHMCS cannot write to a test file in the PHP system directory. | (S)FTP Unable to Write Errors |
SFTP Backup - Login Failed | The system reached the FTP server but it rejected the login details. | SFTP Backup Login Errors |
Last modified: 2025 February 6