Troubleshooting
Last updated November 20, 2026
Most issues with Gorilla Returns fall into a small handful of patterns, and most of those have specific diagnostic tools built into the plugin to tell you exactly what went wrong. This article covers the common ones and where to look for diagnostic information.
The customer portal shows “page reloaded” or no error
Symptom: A customer (or you, testing) enters an order number and email in the portal and clicks Continue, but the page just refreshes with no visible error.
First place to look: Returns → Lookup log. Every portal lookup is recorded with the specific reason it succeeded or failed. The log tells you whether this was an eligibility issue, a bad email match, a missing order, or something else.
Most common cause: the order’s status isn’t in the eligible statuses list. For example, if the order is in shipped status (added by a shipping plugin) and your eligible list is only completed, the lookup silently fails eligibility. Fix at Settings → Portal → Eligible order statuses.
Pro 4.6.2+ shows a plain-English error directly on the portal in these cases (“Your order is in status shipped…”) so customers aren’t left guessing. If you’re seeing silent reloads, make sure you’re on the latest version.
Label generation failed
Symptom: You approve an RMA with “Generate prepaid label automatically” checked, and the admin shows a warning: “Approved, but label generation failed — check logs.”
Common causes, in order of likelihood:
- Invalid EasyPost API key. Go to Settings → Carriers. The connection status at the top should read “Connected to EasyPost” in green. If red, re-paste your Production API key (not the Test key).
- Invalid return address. EasyPost rejects labels where the return address can’t be geocoded. Verify the address at Settings → Carriers → Return address matches a real location with a valid USPS-recognizable format.
- Invalid customer shipping address. Same check in reverse — the shipping address on the order must geocode. Rare, but can happen on international or malformed addresses.
- EasyPost account out of funds. EasyPost requires a pre-funded balance for scan-based labels. If the balance is $0, label generation fails. Check your EasyPost dashboard.
- EasyPost rate-limit or outage. Rare, but transient. Wait 60 seconds and click Regenerate label on the RMA detail view.
Every label-generation failure is logged in Settings → Carriers → Label generation log with the full EasyPost error response. If the cause isn’t obvious from the error message, email the log excerpt to support and we’ll diagnose.
Customer doesn’t see expected exchange variant
Symptom: A customer wants to exchange for a specific variant and reports it isn’t shown as an option.
Most common cause: the variant is out of stock. The portal only shows variants with current stock available, because offering an exchange to a sold-out variant creates a fulfillment problem.
Second cause: the “variant” they want is actually a separate product listing, not a variant of the same product. For example, if “Clear Case” and “Clear MagSafe Case” are two distinct WooCommerce products (not two variants of one parent product), the portal’s variant picker won’t show the MagSafe version because it’s a different product entirely.
Fix: every customer can use the “Something else” option on the exchange step. Picking it reveals a required textarea where they type what they want. Their words appear on the RMA admin and you handle it manually.
Email delivery issues
Symptom: Customers say they didn’t receive the submission confirmation or approval email.
Diagnosis: this is almost always a WordPress mail delivery issue, not a Gorilla Returns issue. WordPress’s built-in wp_mail() uses your server’s PHP mail function by default, which gets flagged as spam by most providers.
Recommended fix: install an SMTP plugin like WP Mail SMTP or FluentSMTP and route email through a real transactional-email service (SendGrid, Amazon SES, Mailgun, Postmark, etc.). This fixes deliverability for all WordPress emails, not just Gorilla Returns’ — order confirmations, password resets, everything.
Verify Gorilla Returns is actually sending: on the RMA detail view, the Email history section shows every email Pro has sent for that RMA, with timestamps. If an email is listed, Pro sent it — the question is why the customer didn’t receive it, which is downstream.
License shows as inactive
Symptom: You’ve pasted your license key, clicked Activate, and the License tab still shows “Inactive” or shows an error.
Common causes:
- License was refunded. If you processed a refund (via SureCart, PayPal, or a chargeback), the license was deactivated as part of the refund. See the Refund Policy.
- Typo in the license key. License keys look like XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX. Copy exactly, including the hyphens.
- Network issue reaching SureCart. If your WordPress server can’t reach the SureCart API (api.surecart.com), license activation fails. Test by visiting that URL from your server; if it fails, contact your hosting provider.
- Clock skew. License signatures are time-sensitive. If your server’s system clock is more than a few minutes off, verification fails. Check your server time.
If none of these apply, email us with your license key and your site URL. We can look it up in SureCart’s admin and tell you why.
Dev mode banner won’t go away
Symptom: A yellow “Dev mode active” banner shows on your Gorilla Returns admin screens even though you’re not in development.
Fix: Go to Returns → Settings → License and look for the Dev mode section. Set the tier to “(none — use real license)” and save. The banner stops appearing.
If Dev mode is active via a wp-config constant (GR_DEV_MODE_TIER), remove the constant from wp-config.php.
If you want to leave Dev mode on but hide the banner, click the X in the banner’s top-right corner — the dismissal is stored per-user and the banner stays hidden until the dev tier changes.
Still stuck?
If you’ve worked through this article and still can’t solve what you’re seeing, email us. The best way to reach us is the built-in support form inside your plugin admin — Returns → Help & Support → Send a message — because it pre-fills your site info, plugin version, WooCommerce version, and PHP version automatically. No “what version are you on?” round-trips.
You can also email us directly at hello@gorillapublic.com. Same inbox. We reply the same business day.