• How it works
  • Sharing function run details
  • Debug a function
  • List of errors

Monitoring and handling errors in production

Functions availability

  • Users that have checkout.liquid customizations need to upgrade to Checkout Extensibility to use Function APIs.
  • Stores on any plan can use public apps that are distributed through the Shopify App Store and contain functions. Only stores on a Shopify Plus plan can use custom apps that contain Shopify Function APIs.
  • Some Shopify Functions capabilities are available only to stores on a Shopify Plus plan. See Shopify Function APIs for details.

This guide describes how you can monitor and debug your functions in production.

How it works

Anchor link to section titled "How it works"

Functions can fail by raising an exception, exceeding memory or time limits, or returning data that doesn't match the schema of the specific Function API. In other cases, the function can run successfully, but return unexpected results due to a bug in the function code.

To aid in debugging issues with a function, information about each function run is stored and made available through the Partner Dashboard. This includes metadata, such as when the run occurred and the shop that it was on, and function run details such as the function input and output.

Function run details are hidden by default for production shops because they can contain Personally Identifying Information (PII), unless they're shared by merchants. Merchants can share function run details by sharing an error report when the function fails or by sharing all function logs for an app.

Development shops are an exception and have all function run details visible.

Sharing function run details

Anchor link to section titled "Sharing function run details"

When a merchant shares function run details from the Shopify admin, you can access them from the app's Extensions section in your Partner Dashboard.

Sharing an error report

Anchor link to section titled "Sharing an error report"

When a function is executed and an error occurs, a warning notification is displayed on the relevant page in the Shopify admin. For example, if you've executed a discount function, then the warning notification appears on the Discounts page.

The warning notification contains information about when errors started occurring. It also includes a link that enables users to share information with developers about function runs that failed.

  1. From the Shopify admin, navigate to the page that's associated with the executed function.
  2. Click the warning notification.
  3. Click Share the error reports with <developer-name>.
  4. Choose whether to include every time the customization ran within the last 24 hours.
  5. Click Share.

An email notification is sent to the Partner organization's specified business contact.

Note

Sharing the last 24 hours of runs includes successful executions.

Share app function logs

Anchor link to section titled "Share app function logs"

Merchants can share all function run details for an app within the past 24 hours, whether there were function failures or not.

  1. From the Shopify admin, navigate to the Apps and sales channels settings.
  2. Select the app that you need to share function run details for.
  3. Click the Share logs button in the Share function logs card.
  4. Click the Share logs button in the modal.

An email notification is sent to the Partner organization's specified business contact.

Debug a function

Anchor link to section titled "Debug a function"

You can debug your function from the app's Extensions section in your Partner Dashboard.

  1. From your Partner Dashboard, go to Apps.
  2. Click the app that you deployed your function to.
  3. Click Extensions.
  4. Click the name of your function.

The function details page contains a list of function runs. After the merchant has consented to share function run details, you can inspect the details of each individual function run.

Note

Functions are deterministic, which means that any time they execute with a given input, they always return the same output. You can therefore copy the input in a function run and accurately reproduce the failing execution locally using Shopify CLI or a unit test.

A screenshot of a function error report in the Partners dashboard

  1. Input (STDIN): The JSON formatted input that you can copy to your clipboard. For illustrative purposes, the input in the screenshot has been omitted.
  2. Output (STDOUT): Contains the output, if the function returned output
  3. Logs (STDERR): Contains the STDERR logs of the function

  4. Error message: Contains the final message sent to STDERR before the function failed

    Caution

    Function logs to STDERR are truncated after 1 kB. Some Wasm toolchains might crash if STDERR fails to write full logs.

List of errors

Anchor link to section titled "List of errors"

The following table provides a complete list of errors that can occur when running your function:

Error name Description
TimeoutError Shopify stopped the function after it ran for over 10 milliseconds (ms).
RunError The function raised an exception.
InstructionCountLimitExceededError Shopify stopped the function after it exceeded the maximum instruction count of 11 million instructions.
StackMemoryLimitExceededError Shopify stopped the function after it exceeded the maximum stack size of 512kb.
LinearMemoryLimitExceededError Shopify stopped the function after it exceeded the maximum linear memory size of 10mb.
InvalidOutputError The function returned malformed or invalid output. This might occur because you printed debugging information to STDOUT, which is reserved for function output. If that's the case, then use STDERR instead.
UnsupportedError The generated Wasm doesn't conform to Shopify Functions standards.
InvalidVariableValueError The function's input query variables metafield was invalid. This can occur if the metafield value doesn't conform to the variables definitions, or if the metafield type isn't json. For more information, refer to using variables in input queries.

On this page

  • How it works
  • Sharing function run details
  • Debug a function
  • List of errors