Restore offloaded images retry skips previously failed rollback items

[pirate-bot]

Summary

Users restoring images from Optimole Cloud back to their WordPress Media Library can get stuck after a failed restore attempt.

Expected behavior: after a restore attempt fails and the user starts the restore process again, remaining offloaded images are considered for restore.

Actual behavior: images from a previous failed rollback attempt can be skipped on later restore attempts, so the restore process may finish without bringing those files back.

Impact: affected users may be unable to complete the restore from Optimole Cloud using the plugin workflow and may see images remain unavailable locally.

Customer context

• Product / area: Optimole, Image Storage / Restore Offloaded Images
• Version: Unknown from available evidence
• Environment: Free Optimole plan; active Optimole account from internal account lookup; Windows 10 and Chrome reported by HelpScout beacon
• Integration / third party: None provided
• Reported error / symptom: Customer reported that restoring images to the Media Library was not successful after using the website restore process
• Impact: Customer cannot complete image restore through the plugin workflow, based on the thread text

Reproduction notes

Reported steps from the thread:

1. Customer attempted to restore images to the WordPress Media Library.
2. Customer used the restore process on their website.
3. Restore was not successful.

Repository-derived reproduction path to verify:

1. Have an attachment marked as offloaded by Optimole.
2. Trigger or simulate a rollback failure so the attachment receives optimole_rollback_error.
3. Start the restore/rollback process again from Optimole Image Storage.
4. Observe whether the failed attachment is skipped because rollback selection excludes items with that rollback-error marker.

Missing from the customer report: plugin version, site debug logs, visible error messages, number of failed images, and whether WP-Cron or server/security constraints affected the restore process.

Diagnosis

Conclusion

The code path for restoring offloaded images has a confirmed retry defect. Rollback failures add optimole_rollback_error metadata to attachments, and later rollback queries explicitly exclude attachments with that metadata. The dashboard/offload clear-errors route only deletes optimole_offload_error, not rollback errors. This suggests a user who reruns restore after a rollback failure can see the process skip the failed attachments rather than retry them.

The HelpScout thread does not provide debug logs or a specific failed attachment, so the customer’s exact failure mode is not proven. The repository evidence is sufficient for a product bug in the retry path.

Where this likely occurs

• User-visible surface: Optimole dashboard, Settings → Image Storage → restore/rollback from Optimole Cloud.
• assets/src/dashboard/parts/connected/settings/OffloadMedia.js — onRollbackdMedia() lines 138–154: starts rollback_images after conflict checks and saving settings. Unlike the offload path at lines 117–132, this rollback handler does not clear prior transfer errors before calling callSync().
• assets/src/dashboard/utils/api.js — callSync() lines 479–589: polls number_of_images_and_pages for rollback_images and updates progress based on the server count/status returned by the REST endpoint.
• inc/rest.php — Optml_Rest::number_of_images_and_pages() lines 824–836: passes the requested action to Optml_Media_Offload::move_images().
• inc/rest.php — Optml_Rest::clear_offload_errors() lines 840–849: exposes the clear-errors endpoint, but it delegates to a method named for offload errors only.
• inc/media_offload.php — Optml_Media_Offload::rollback_and_update_images() lines 874–989: multiple rollback failure branches mark attachments with self::META_KEYS['rollback_error'].
• inc/media_offload.php — Optml_Media_Offload::get_images_or_pages_query_args() lines 1585–1603: rollback attachment selection requires optimole_offload = true and excludes attachments where optimole_rollback_error exists.
• inc/media_offload.php — Optml_Media_Offload::clear_offload_errors_meta() lines 2677–2685: deletes only self::META_KEYS['offload_error'], leaving self::META_KEYS['rollback_error'] intact.
• Relevant git history: 3eadcd29e introduced the rollback-error exclusion in the rollback query; 1712febfd changed the clear-errors helper to delete only optimole_offload_error; 8c9d8db3 later touched the rollback UI flow with commit message fix: rollback issue; 3bc227fd added offload restrictions and automatic revert behavior for accounts without offloading support.

Engineering notes

• The defect is scoped to attachments that have already received optimole_rollback_error. A first clean rollback attempt is not proven affected by this specific issue.
• The documented troubleshooting flow says the rollback process can be restarted after unexpected errors. The inspected plugin path appears to make errored rollback items ineligible for subsequent bulk rollback selection.
• The customer is on a free Optimole plan. Current product behavior also includes offload restrictions for free users and automatic revert handling for accounts without offloading support, but the inspected defect is independent of plan gating once rollback has started.
• WordPress core internals for download_url(), wp_handle_sideload(), wp_create_image_subsizes(), and related upload helpers were not inspected in this workspace. The diagnosis relies on Optimole’s own metadata writes, query filters, REST endpoint, and dashboard flow.

Test coverage status

• Relevant PHP coverage exists in tests/test-media.php — Optml_Media_Offload::rollback_images() is exercised by test_image_sync() lines 326–345 and test_image_rollback() lines 348–358.
• The inspected tests cover a successful rollback path and media metadata/file restoration assertions.
• No relevant coverage was found during inspection for retrying a rollback after an attachment has optimole_rollback_error, or for the dashboard rollback flow clearing/not clearing prior rollback errors.

What to verify or explore next

• Reproduce with an offloaded attachment, set or trigger optimole_rollback_error, then start the dashboard restore process again and confirm whether the attachment count excludes that item.
• Verify the same retry behavior through WP-CLI rollback, since it uses the same rollback query path.
• Inspect logs from a failed rollback attempt to confirm which failure branch set optimole_rollback_error in real usage.
• Run the existing media test suite around tests/test-media.php and add focused coverage for the retry-after-rollback-error scenario if reproduction confirms it.

Unknowns / follow-up

• The ticket does not include Optimole plugin version, WordPress version, debug logs, count of affected attachments, or whether the restore attempt showed an error notice.
• The customer’s exact restore failure may involve hosting, cron, firewall, account domain allowlisting, or an Optimole Cloud API response; those are not proven from the transcript.

Confidence

Confidence: 82/100

Repository inspection shows a definite retry-path defect in the Optimole rollback workflow: failed rollback items are marked and then excluded from later rollback queries, while the available clear-errors path only removes offload errors. The customer report is sparse, so the customer-specific match is likely rather than proven.

---

Source: HelpScout #3379202390
Generated by bug-report-triage (ID: bug-report-triage_6a4d30a7b8bc30.72335324)

[kushh23]

This appears to be a assumption based report as no critical details are presented in the ticket. Only a basic query from user about rollback not working.