Skip to main content

Function settings extensions can now report several errors at once

Function settings extensions can now report several errors at once. When your s-function-settings onSubmit handler rejects with an AggregateError, the Shopify admin shows every error on discount and checkout rule pages instead of only one. No action is required.

What changed

Previously, the admin showed one error when your extension rejected the promise you passed to event.waitUntil() in onSubmit, using the message of that error.

Now you can reject with an AggregateError, and the admin shows the message of each entry in its errors list. Each entry is an Error, and you can give it a code string.

  • The admin shows up to 10 errors. Each message is trimmed to 300 characters, and duplicate messages appear once.
  • Your onError handler receives the same entries, with their codes, so you can mark the fields in your own UI.
  • An entry with no code, or a code that is empty or longer than 64 characters, gets a default code: UNKNOWN on discount pages and EXTENSION_ERROR on checkout rule pages.
  • Rejecting with a single Error still works and shows one error.

The onerror property of s-function-settings is now typed as the AggregateError it receives in @shopify/ui-extensions 2025-10, 2026-10, and the 2027-01 release candidate.

Who's affected

This applies to apps with a function settings extension on discount or checkout rule pages, built with Polaris web components on API version 2025-10 or later.

Extensions on earlier API versions keep the previous behavior and show a single message. Extensions that reject with a single Error also keep working as before.

Why this matters

When a merchant fills in several fields incorrectly, they now see every problem after one save. They do not have to fix one field, save, and then find the next error.

What to do

No action is required. To report several errors, reject with an AggregateError of Errors in your onSubmit handler:

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 > 0) {
throw new AggregateError(errors, 'Settings are not valid');
}
// apply your metafield changes here
}

<s-function-settings
onSubmit={(event) => event.waitUntil(save(settings))}
onError={(event) => {
for (const error of event.error.errors) {
console.log(error.code, error.message);
}
}}
>
{/* your fields */}
</s-function-settings>

This sample checks two fields and throws one AggregateError with an Error per invalid field. Replace the checks and codes with your own. To test your extension, save settings with several invalid fields on a development store and confirm that the admin lists each error.

Related docs

Was this page helpful?