Troubleshooting

This page collects the issues that come up most often in production, each with a short diagnosis and a concrete fix. Start here before opening a support ticket — and start with the connection test, which answers most of them in one click.

What you’ll learn

• How the built-in connection test narrows a problem down in seconds
• Why thumbnails sometimes disappear and how to refresh OAuth tokens
• How to speed up a slow-feeling gallery
• Why print-shop emails go missing and how to fix delivery
• How to recover from a redirect-mismatch OAuth error
• How to roll back a plugin update that broke your site

Prerequisites

• The plugin installed and activated
• Admin access to the WordPress site

Start here: the connection test

Go to Customer Cloud Gallery → Settings and click Test connection on the provider card. It runs four checks in order and stops at the first one that fails, so the first red line is your actual problem:

1. Access token — can the plugin still talk to Google Drive or Dropbox, and refresh its token?
2. Folder — can it read your main folder? The result names the folder and counts the subfolders and images it found.
3. Image download — it actually downloads one image. This is the check that catches permissions which allow listing but not reading.
4. Thumbnail cache — is the cache folder on your server writable?

Each failure comes with a plain-language hint. Two are worth knowing in advance:

“Folder could not be read” on Dropbox. Your Dropbox app most likely uses App folder access instead of Full Dropbox. Change it in the Dropbox App Console (or move the photos into the app folder), then disconnect and reconnect here.

“Image download failed” on Dropbox. The app can list files but not read them: the files.content.read permission is missing. Enable it under Permissions in the Dropbox App Console, click Submit, then disconnect and reconnect — permissions are baked into the access token, so an existing connection keeps the old, narrower one.

If a test is skipped rather than failed (“no folder to test yet”, “no image found”), that is not an error — the plugin just had nothing to test with. Set a main folder or put an image in it and run the test again.

Images don’t show

Diagnosis. Three usual causes: (1) the OAuth refresh token expired (most common when you skipped Publish App in the Drive consent screen and haven’t used the connection for 7 days); (2) the source folder was renamed, moved or its sharing settings changed in the cloud; (3) the file is a format the browser doesn’t render (HEIC on older browsers, RAW files).

Fix.

1. Run the connection test above — it tells you within seconds whether this is a token, a folder, a permission or a cache problem. If it reports Not connected, click Connect again on the provider card.
2. For Drive specifically, make sure you clicked Publish App on the OAuth consent screen — see Google Drive setup step 4.
3. Confirm the folder still exists at the same path/ID and contains image files. If you moved the folder, paste the new ID into the gallery editor.
4. For HEIC, either convert to JPEG before uploading, or test in Safari/iOS where HEIC is native. The plugin streams whatever the cloud returns; it does not transcode.

Slow gallery

Diagnosis. First-load is always slower because thumbnails are being fetched from Drive/Dropbox and cached locally. After the first visitor, subsequent visitors hit the local cache and load fast. If it stays slow on repeat visits, suspect a caching plugin conflict or unoptimised originals.

Fix.

1. Visit the gallery once yourself (in a private window) before sending the link to the client — this primes the cache.
2. Make sure your caching plugin (WP Rocket, W3 Total Cache, LiteSpeed) isn’t excluding /wp-content/plugins/customer-cloud-gallery/ from caching.
3. If your originals are 50–100 MB RAW or 24-megapixel JPEGs, consider exporting client deliverables at 12–16 MP — visitors download originals, but thumbnails are independent of original size and your server bandwidth is independent of original size (originals stream straight from the cloud).

Print shop emails don’t arrive

Diagnosis. Almost always a wp_mail() delivery issue rather than a plugin bug. Shared hosting often refuses to send email from PHP, or the message lands in spam because it’s coming from wordpress@yourdomain.com with no SPF/DKIM record.

Fix.

1. Install an SMTP plugin: WP Mail SMTP, FluentSMTP or Post SMTP.
2. Configure it with a transactional email service (SendGrid, Mailgun, Brevo, Amazon SES, Postmark — all have free tiers).
3. Send a test email to confirm delivery.
4. Check the customer’s spam folder for the first real order; ask them to whitelist your domain.

OAuth redirect mismatch

Diagnosis. The redirect URI in your Google Cloud OAuth client (or Dropbox app) doesn’t exactly match the URL the plugin tells your provider during the OAuth dance. Even a trailing slash, http vs https, or www. vs no-www. triggers this error.

Fix.

1. In the plugin: open Customer Cloud Gallery → Settings, expand the relevant provider’s setup guide, and copy the redirect URI from the code block.
2. In the cloud console (Google Cloud Console → Credentials, or Dropbox App Console → Settings), open the OAuth client/app.
3. Replace the existing redirect URI with the exact value from step 1. Save.
4. Reconnect from the plugin.

If your site is reachable on multiple URLs (e.g. example.com and www.example.com), make sure the canonical home URL in Settings → General matches what you registered.

Gallery hides behind the header

Diagnosis. Your theme uses a transparent or absolute-positioned header that overlays page content. The top row of the gallery sits behind it, so visitors only see partial thumbnails.

Fix. Add a Spacer block above the gallery shortcode in the page editor:

1. Open the page in the editor.
2. Click the + above the Shortcode block, add a Spacer block.
3. Set its height to roughly your header height (80–120 px works for most themes).
4. Update the page.

This is documented as a step in Password protection and Print shop setup because it’s so common.

Plugin update broke something

Diagnosis. A new version introduces a regression specific to your theme, server PHP version, or a plugin you have installed.

Fix.

1. Go to Plugins → Installed Plugins.
2. Find Customer Cloud Gallery and click View Installed Versions in the Updates column (this requires the WP Rollback plugin or a recent WordPress version with native rollback support).
3. Choose the previous stable version (e.g. roll back from 1.12.0 to 1.11.8).
4. Confirm the rollback. WordPress reinstalls the older version.
5. Open a support ticket so the regression can be fixed in the next release.

If your hosting environment doesn’t support native rollback:

1. Download the older version’s ZIP from the WordPress.org plugin page (Advanced view → Previous Versions).
2. Deactivate the plugin (your galleries and settings are kept).
3. Delete the plugin (your galleries and settings are still kept — uninstall data only happens on Delete with the explicit confirmation).
4. Upload the older ZIP via Plugins → Add New → Upload Plugin.
5. Activate.

Common mistakes

“Disconnect and reconnect” doesn’t fix the disconnected state. You have multiple Drive/Dropbox accounts in your browser session. After clicking Connect, double-check that the consent screen shows the right Google/Dropbox account (top-right of Google’s screen). Sign out of the wrong one in another tab if necessary.

Cleared the visitor cookie and now favourites are gone. Favourites are tied to the random visitor cookie, not the WordPress login. Clearing cookies wipes the visitor’s favourites — this is by design (privacy) and there’s no “log in to recover” path. Tell clients to favourite in one session if possible.

Next step

If your problem isn’t covered here, see the FAQ for higher-level questions, or contact support via the link on the plugin website.