Mobile App: Troubleshooting

From WHMCS Documentation

Connection and Access

You must configure an API Access Key to use WHMCS Mobile

This error indicates that you didn't add the API Access Key to the configuration.php file successfully. Please ensure you've added the API Access Key to your configuration.php file and then enter that value in the Access Key field into the WHMCS Mobile app.

For step-by-step instructions, see Mobile App: Connecting to WHMCS.

Invalid special character in Access Key

This indicates that your access key includes one or more unsupported characters. The mobile app only supports numbers, letters, and the following special characters:



! @ # $ % . ( ) * [ ] - _


To resolve this issue:

  1. Open the configuration.php file found in your WHMCS installation directory using a text editor.
  2. Look for the $api_access_key variable.
  3. Remove or replace any unsupported characters.
  4. Save changes to the configuration.php file and upload to your server
  5. Return to the WHMCS Mobile App and re-enter the updated API Access Key value
  6. Click the Validate Credentials button to test the connection

Upon success, the connection profile will be created and saved and you will be redirected to the app dashboard.

Access Denied

Our mobile app uses the API to communicate with your WHMCS installation. The Administrator Roles of staff using the app will require the "API Access" permission.

To grant this permission:

  1. Go to Configuration () > Manage Admins or, prior to WHMCS 8.0, Setup > Staff Management > Administrator Roles.
  2. Edit the desired role.
  3. Check API Access.
  4. Click Save Changes.

Unable to connect. Please check the installation and device are online and try again

Please ensure that you are entering the URL as "https://whmcs.example.com/" or "https://example.com/whmcs/ with the trailing slash at the end.

The WHMCS URL should be the URL to the frontend (client area) in System URL in the General tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.

Authentication Failed

Authentication Failed indicates that the admin user name or password supplied in the profile are being rejected. Type your username and password again to make sure that they are correct.

Viewing and Managing Clients

Error generating JSON encoded response

This error has two typical causes; an invalid (non-utf-8) character in the client's profile/service data, or the WHMCS installation is using a non-utf-8 character set. The following sections show how to identify the cause and the corresponding solutions:

Invalid Character in Profile/Service Data

If the "Error generating JSON encoded response" error is encountered only when accessing certain clients:

  1. Navigate to Clients > View/Search Clients.
  2. Select the client in question.
  3. Click on their Profile tab.
  4. Examine all the fields and ensure all the fields contain valid letters, numbers and symbols.
  5. Next click on the Products/Services tab.
  6. Examine each of the client's service records and ensure all the fields contain valid letters, numbers and symbols.
Service Password with Invalid Characters

The most common cause of this error is a non-decryptable service password.

To resolve:

  1. Re-enter the service password (or clear out the field if a password is no longer required).
  2. Click Save Changes.
  3. Repeat the process for any other clients experiencing the same error to ensure they all contain a valid service password.

The client's details should now load successfully in the WHMCS Mobile App.

Non UTF-8 Character Set

If the "Error generating JSON encoded response" error is encountered immediately upon accessing the Clients tab in the Mobile App or when accessing all clients:

  1. Go to the Localisation tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings.
  2. Make certain that System Charset is utf-8. Change the value if necessary.
  3. Click Save Changes.
  4. Ensure that the following line is present in the WHMCS configuration.php file:
    $mysql_charset = 'utf8';
    If it is not present, add the line and save the file.

The client's details should now load successfully in the WHMCS Mobile App.