Multiple Error Reporting Now Available for Function Settings Extensions

Shopify’s latest developer update lets function‑settings extensions return several validation errors at once, giving merchants instant feedback on every issue. Learn what changed, who it impacts, and how to implement the new AggregateError pattern today.

Multiple Error Reporting Now Available for Function Settings Extensions
7 sections

Shopify just rolled out a game‑changing improvement for developers building function‑settings extensions on discount and checkout rule pages. By allowing an extension’s onSubmit handler to reject with an AggregateError, the admin UI can now display up to ten distinct validation messages in a single save attempt. This post breaks down the change, explains who needs to care, and walks you through the exact code you’ll need to start leveraging the new multi‑error reporting.

What’s New?

Previously, if your extension rejected the promise passed to event.waitUntil() with a single Error, the admin UI would surface only that one message. Merchants often had to fix a field, click Save, then discover the next error on a subsequent attempt. The new behavior expands the contract: when you throw an AggregateError containing multiple Error objects, the admin lists each one (up to ten), trims messages to 300 characters, and de‑duplicates identical texts. Each error can also carry a custom code, enabling you to highlight the exact field that needs attention.

Who Is Affected?

The update applies to any app that uses a s-function-settings extension on discount or checkout rule pages and is built with the Polaris web components on API version 2025‑10 or later. Extensions still on older API versions keep the original single‑error behavior, and extensions that continue to reject a single Error remain fully functional. In short, if you’re already targeting the latest API, you’ll automatically see the new multi‑error UI without any extra configuration.

Why It Matters for Merchants

From a merchant’s perspective, the change eliminates a frustrating trial‑and‑error loop. When a form contains several invalid fields—say, a missing minimum quantity and a percentage value above 100%—the admin now surfaces both messages immediately. Merchants can correct all issues in one go, speeding up discount creation and reducing support tickets caused by “only one error shows up” confusion. It’s a small UX tweak that delivers a noticeably smoother workflow.

How to Implement the AggregateError Pattern

Below is a minimal, production‑ready example that checks two fields and throws an AggregateError when either validation fails. Notice the helper fieldError function that attaches a custom code property to each Error—this code surfaces in the onError event, letting you map the error back to a specific UI component.

javascript

function fieldError(code, message) {

return Object.assign(new Error(message), {code});

}

async function save(settings) {

const errors = [];

if (!settings.minimumQuantity) {

errors.push(fieldError('MINIMUM_QUANTITY_REQUIRED', 'Enter a minimum quantity.'));

}

if (settings.percentage > 100) {

errors.push(fieldError('PERCENTAGE_TOO_HIGH', 'Percentage can be at most 100.'));

}

if (errors.length) {

throw new AggregateError(errors, 'Settings are not valid');

}

// Apply metafield changes or other side‑effects here

}

<s-function-settings

onSubmit={event => event.waitUntil(save(settings))}

onError={event => {

for (const err of event.error.errors) {

console.log(err.code, err.message);

// You could also highlight the offending field based on err.code

}

}}

>

{/* Your custom fields go here */}

</s-function-settings>

Key points to remember:

  • The admin shows up to 10 errors; any extra errors are silently dropped.
  • Each message is trimmed to 300 characters, so keep error text concise.
  • Duplicate messages appear only once, preventing clutter.
  • If an error entry lacks a code or the code is longer than 64 characters, the admin falls back to UNKNOWN (on discount pages) or EXTENSION_ERROR (on checkout rule pages).
  • The onError handler’s type signature now reflects the AggregateError shape, so TypeScript users get proper autocomplete in the @shopify/ui-extensions 2025‑10, 2026‑10, and 2027‑01 RC releases.
  • Testing Your New Validation Logic

  • Deploy the updated extension to a dev store.
  • Navigate to the discount or checkout rule page where the extension lives.
  • Intentionally leave both fields invalid and click Save.
  • Verify that the admin UI lists both error messages, each with its custom code.
  • Use the console.log output from the onError handler to confirm you receive the same error objects in your JavaScript.
  • Adjust the error‑message length and duplicate scenarios to see how the UI de‑duplicates and trims content.
  • What You Need to Do Now

    Good news—no immediate migration is required. Existing extensions continue to work exactly as before. However, to take full advantage of the new experience you should:

  • Update your onSubmit logic to collect validation errors in an array.
  • Throw an AggregateError instead of the first Error you encounter.
  • Attach meaningful code strings (max 64 characters) to each error for better UI mapping.
  • Adjust any custom onError handling to iterate over event.error.errors instead of assuming a single error.
  • Run the test steps above on a staging store before pushing to production.
  • Conclusion & Next Steps

    Shopify’s multi‑error reporting is a subtle but powerful quality‑of‑life upgrade for both developers and merchants. By surfacing every validation issue in one go, you reduce friction, cut down on back‑and‑forth saves, and deliver a cleaner, more professional discount‑creation experience. Update your function‑settings extensions today, test the new flow, and watch your merchants thank you for the smoother workflow. Need help adapting your code or testing on a live store? Reach out in the Shopify Community forums or drop a comment below—we’re happy to help!

    Tags
    Sources

    Related Articles

    Embedding YouTube & Vimeo Directly via File Reference Metafields in Shopify API 2027-01

    Embedding YouTube & Vimeo Directly via File Reference Metafields in Shopify API 2027-01

    Shopify’s 2027-01 API now lets file reference metafields store YouTube and Vimeo video URLs, unlocking seamless video embeds for merchants and developers. Learn what changed, who it affects, and how to implement the new feature today.

    November 20, 20265 min
    Why Your Shopify App Must Enable IP Allowlist by Tomorrow (Nov 20 2026)

    Why Your Shopify App Must Enable IP Allowlist by Tomorrow (Nov 20 2026)

    Shopify’s latest security deadline forces public and custom apps to add an IP allowlist. Learn what changed, who’s impacted, and step‑by‑step how to stay compliant before the November 20 cut‑off.

    November 19, 20265 min
    Show Image Swatches for Product Options via the Catalog API

    Show Image Swatches for Product Options via the Catalog API

    Shopify’s Catalog API now returns image swatches for product option values, letting developers display color or pattern previews directly in pickers. Learn what changed, who it impacts, and how to implement swatches with zero‑effort updates.

    November 19, 20264 min
    Why Network Access Declarations Are Now Mandatory for Online Store Apps

    Why Network Access Declarations Are Now Mandatory for Online Store Apps

    Shopify now requires apps that run on the online store to declare their network access in shopify.app.toml. Learn what changed, who’s affected, and how to update your app before the December 2026 deadline.

    November 19, 20264 min