Use this page if Refer a Friend Premium won’t install or activate, if your licence key is rejected, or if WooCommerce → Refer a Friend shows a blank screen, a spinner that never ends, or settings that don’t save.
The plugin won’t install
| Error | Cause | Fix |
|---|---|---|
| The package could not be installed. No valid plugins were found. | You uploaded the wrong file. Some browsers, such as Safari, unzip downloads automatically, and the file you uploaded was re-zipped or is a different archive. | Download the plugin again from Purchase History and upload that .zip without unzipping it. |
| The uploaded file exceeds the upload_max_filesize directive. | Your server’s upload limit is too small. | Ask your host to raise it, or unzip the plugin and upload the folder to wp-content/plugins/ over SFTP. |
| Destination folder already exists. | An older copy is already installed. | Choose Replace current with uploaded when WordPress offers it. Your settings are kept. |
The plugin won’t activate
If WordPress says the plugin triggered a fatal error, or the site breaks right after activation, the free version is almost always still active.
- Go to Plugins → Installed Plugins.
- Deactivate and delete Refer A Friend for WooCommerce by WPGens, the free version.
- Activate Refer a Friend for WooCommerce PREMIUM again.
Your settings and customers’ referral codes are kept. If the site is down and you can’t reach the admin, rename the folder of either plugin in wp-content/plugins/ over SFTP or in your host’s file manager, then log in and fix it from there.
The licence key is rejected
Licence errors only affect updates. The plugin keeps working without a licence. See the table of licence messages in Install and activate Premium.
The settings page is blank or keeps loading
The Refer a Friend admin is a JavaScript app that loads its data from your site’s REST API at /wp-json/gens-raf/v1/. A blank screen means the app didn’t load, or it couldn’t reach that API.
- Check your role. You need the Administrator or Shop Manager role.
- Clear caches. Clear your browser cache and any admin caching or minification in your performance plugin. Then reload with Ctrl+Shift+R, or Cmd+Shift+R on a Mac.
- Check the REST API. Go to Tools → Site Health. If it reports that the REST API encountered an error, fix that first. Security plugins and firewalls that block or restrict
/wp-json/for logged-in users are the usual cause. Allowgens-raf/v1. - Look for a JavaScript error. Open your browser’s developer tools on the blank page, then the Console tab. An error that names another plugin points to a conflict.
- Check the API response. In developer tools, open the Network tab, reload, and click the
settingsrequest. A 401 or 403 response means something is blocking the API. A 500 response means a PHP error, which will be in your PHP error log. - Test for a conflict. Deactivate other plugins except WooCommerce and Refer a Friend, then reactivate them one at a time. Use a staging site if you have one.
WooCommerce 9.8.0 and 9.8.1 had a bug that broke the admin of plugins built with React, including this one. Updating WooCommerce fixes it. If you added a workaround snippet at the time, you can remove it. See Known compatibility issues.
Settings don’t save
- Look for a red message under a field. The form won’t save while a required field is empty or invalid, and the message may be below the visible area. Scroll through the whole tab.
- Wait for “Settings Saved.” after clicking Save. If nothing appears, check the Network tab for the
settingsrequest as in step 5 above. - Clear your page cache after saving if the shop still shows the old settings.
Check it worked
WooCommerce → Refer a Friend opens with Advocates, Orders and Settings in the sidebar, and saving a setting shows “Settings Saved.”