--- title: "Testing and Troubleshooting Transforms" slug: "testing-and-troubleshooting-transforms" tags: ["troubleshooting"] status: "update" updated: 2026-10-13T15:35:13Z published: 2026-10-13T15:35:13Z canonical: "docs.unqork.io/testing-and-troubleshooting-transforms" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Testing and Troubleshooting Transforms A [transform](/unqorkai/docs/transforms-1) is a set of rules that converts submission data from one format into another. When creating transforms in Unqork, errors or unexpected outputs might occur. > [!TIP] > Before testing manually, describe the transform and the unexpected output to the [Build Agent](/unqorkai/docs/build-agent-reference). The agent can often identify syntax errors, mapping mistakes, or configuration issues directly. Test transforms using the **Test Transform** section in the transform, or the **DevTools Network** tab when the transform is applied in a different module. Transform errors typically do not identify where the error occurred, so this article also covers how to identify and resolve common errors. ## Testing Transforms Using the Test Transform Section Some transforms exist in the same module as the submission data; to test these, use the **Test Transform** section in the transform. If the transform is applied in a different module, use the **DevTools Network** tab instead. Before using a transform in production, open the module in Express View using **View in App** and make a submission. Then copy the submission ID and paste it into the **Test Transform** section. To test a transform: 1. In the Module Builder, click **View in App**. 2. Enter the information in the module. 3. Save the module's submission data. > [!TIP] > Save the module's submission data to the database before copying the submission ID. For example, use a [Button component](/unqorkai/docs/button-component) configured to submit the form. 4. Copy the **submission ID**. > [!NOTE] > The submission ID is the middle segment of the three alphanumeric codes in the Express View URL. The URL follows this structure: `https://your-environment.unqork.io/{module-id}/{submission-id}/{module-id}`. 5. Open the module in the Module Builder. 6. At the top of the Module Builder, click the **Definition** drop-down. 7. Select **Transforms**. Existing transforms display in the list. 8. Open the transform to test. 9. Locate the **Test Transform** section. 10. In the **Submission ID** field, paste the submission ID. 11. Click **Run Test**. The field populates with the submission data, and the transformed result displays in the field. ## Testing Transforms Using the Network Tab When the module where a transform is created differs from where it is applied, use the **DevTools Network** tab. Switching between these tabs lets Creators apply edits and check results in real time. To test a JSON transform in the Network tab, open three web browser tabs: | Web Browser Tab | Description | | --- | --- | | Transform Page | Use this tab to edit the transform through **Transforms** in the Module Builder **Definition** drop-down. | | Module Builder Page | Use this tab to reference the module where the [Plug-In component](/unqorkai/docs/plug-in-component) calls data and the transform. | | Express View Page | Use this tab to view transform test results. | ### Setting Up the Transform Tab The first tab to open is the JSON transform. Navigate to **Transforms** through the **Definition** drop-down in the Module Builder where the transform was created. Make any edits and save the transform to test the changes. ### Setting Up the Module Builder Tab The second tab is the module with the Plug-In component that triggers the transform. Open this module in the Module Builder. For this example, configure the Plug-In component using the **Execute with Input Data** internal service. Before testing the transform, confirm the Plug-In component is configured correctly. If the configuration is wrong, the transform will not work as expected. For the **Execute with Input Data** service, check the following: 1. The Plug-In component's **Inputs** table maps to the correct transform module ID, name, and data to transform. 2. The Plug-In component's **Outputs** table maps to where the output is stored. For a JSON transform, the output name is `jsonData`. 3. From the **Internal Service** drop-down, select **Execute with Input Data**. 4. Confirm the **Data Source URL** is accurate. 5. Click **Save**. ### Setting Up the Express View Tab In the third tab, use the DevTools **Network** tab to view results. To access the Network tab: 1. In the Module Builder, open the module where the input or output transform is triggered. 2. Click **View in App**. 3. Right-click anywhere on the Express View page. 4. Click **Inspect**. A panel opens in the browser. 5. At the top of the panel, click the **Network** tab. Once the module runs in Express View, the Network tab populates with results. From the list, select the **transformer** to view the output. If an error occurs, the transformer displays in red. If the transform Plug-In component is not triggered, the transformer does not display in the Network tab. ## Troubleshooting Common Transform Errors Transform errors do not identify where an issue occurred. When a transform encounters an error, it stops at the first one. ### Configuration Errors Sometimes a transform does not work due to a configuration error. These issues can occur in the following cases: - A [Plug-In component](/unqorkai/docs/plug-in-component) trigger is missing. - Entries in the Plug-In component's **Inputs** or **Outputs** table are missing or incorrect. - An internal service is not selected. #### Troubleshooting Missing Plug-In Component Triggers If the Plug-In component is not working, confirm its trigger is configured correctly. #### Troubleshooting Inputs and Outputs Another common configuration error involves the **Inputs** and **Outputs** tables in the transform Plug-In component. If incorrect values are entered, the transform returns an error or unexpected data. If required information is missing from the Inputs or Outputs tables, the transformer displays the `Missing POST variable data` error in the Network tab. For example, when using **Execute with Input Data**, the module ID, transform name, and data to transform must all be present in the Inputs table. > [!NOTE] > If the transform uses a Pre-Request Transform trigger, the Inputs and Outputs do not exist in the Plug-In component. To resolve this error, add the necessary values to the transform. #### Troubleshooting Missing Internal Services An error might occur if no internal service is selected for the transform Plug-In component. In the Module Builder, configure the transform Plug-In component using either the **Execute with Input Data** or **Pre-Request Transform** internal service. If neither option is selected, the following error displays in the DevTools Network tab: `Cannot POST /`. ### Syntax Errors Each data type in a transform follows a specific set of syntax rules. This section covers JSON transform syntax errors. For other data types like XML, no error displays in the Network tab; the transform outputs incorrect data instead. If a JSON transform has incorrect syntax, it returns the `Could not parse NJK-transformed data to JSON` error. Most syntax errors are simple mistakes. Before running a transform, check the following: - Transform objects, variables, and arrays use the correct notation. - Each line that contains a value ends with a comma. The exception is the last item in an object or array. - Capitalization in the transform is correct. JSON is case-sensitive, so an incorrect capital letter will cause an error. - Keys in key-value pairs are surrounded by double quotes. ### Mapping Errors Mapping errors occur when a transform sends data to the wrong key or field. This can return the `Could not parse NJK-transformed data to JSON` error. For example, say a transform has two template variables. One variable stores a client name as text, and the other stores their age as a number. If the variables are accidentally switched and assigned to the wrong keys, the transform assigns the wrong values and the data displays incorrectly. Mapping an array incorrectly also results in a mapping error. When writing Boolean, number, or string variables, single template variables might be used. For arrays, the variables must be included in loops to avoid a mapping error. Referencing an array with a single template variable returns the `Could not parse NJK-transformed data to JSON` error. ### Data Type Errors Writing variables, objects, or values in the wrong data type returns a transform error, though the specific error or output varies. #### Mislabeling Strings Mislabeling strings in a transform returns an error. Say a JSON transform is written with template variables. The template variable stores a string value that was not wrapped in double quotation marks. The transform breaks and returns a `Could not parse NJK-transformed data to JSON` error. #### Mislabeling Numbers, Booleans, or Arrays Forgetting to add quotes to a string value returns an error. But adding double quotes to a number or Boolean value does not cause an error. Instead, the transform runs and returns incorrect output. If a transform includes a number value in quotes for a variable, it returns the number value as a string. While the transform runs without an error, it does not return the expected values. Mislabeling arrays also returns incorrect data. An array can contain string, number, or Boolean values as elements. When writing a JSON transform, arrays must be in a loop. Mapping to an array with a single template variable results in an error. But if quotes are added to the variable, the transform does not return an error. Instead, it runs and returns `[object Object]` for each array element. Say a transform stores insurance clients and their dependents. In the transform, a single template variable maps to an array with the dependents' names. To store the variable as a string, it is written in double quotes. When the transform runs and the transformer is opened in the DevTools Network tab, it returns `[object Object]` for each element. ## Best Practices When writing transforms, troubleshooting an error or incorrect output can be a challenge. Test early and often. Even with the right preparation, errors might still occur. The [Build Agent](/unqorkai/docs/build-agent-reference) can help diagnose transform issues. Paste the transform and the error message into the agent for analysis. For issues that require manual investigation, apply the [investigate, isolate, and terminate approach](/unqorkai/docs/troubleshooting-unqork-applications): 1. **Investigate and Replicate**: Understand the context of the unexpected behavior and, if possible, replicate the issue. 2. **Isolate**: Narrow down the search to identify the cause. 3. **Terminate**: Once the cause is identified, fix it. > [!TIP] > As portions of the transform are removed or added, check syntax before running; a misplaced comma or open bracket can introduce a separate error. --- **Changelog** | Date | Change | | --- | --- | | 2026-10-09 | Added inline links throughout all h2 sections (transform, Build Agent, Plug-In component, investigate/isolate/terminate); stale sweep review. | | 2026-07-16 | Initial publication. | The DevTools Console helps you securely store, build, test, and deploy your software. Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View. The Unqork front-end application framework that delivers Creator-built applications to end-users. Express is the layer end-users interact with—the published forms, screens, and navigation built in the Module Builder. Express is distinct from Express View, which is a Creator-facing preview tool in the IDE. A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform. JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data. A definition Enter inputs components and actions you want the component to perform.. Enter outputs components and actions you want the component to perform. Triggers activate another component when certain requirements are met. Trigger types include Concurrent, Post, and Error. Some components do not have the ability to trigger others. Enter inputs components and actions you want the component to perform. Data types are a classification of data that determines how it is stored and interpreted. Data types are a classification of data that determines how it is stored and interpreted. Extensible Markup Language (XML) is markup language that lets you define and store data in a shareable way. An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity. An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases. A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases. An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. The Boolean data type accepts one of two values: true, or, false. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. Elements are are what you use to build Unqork applications. Elements include modules, workflows, Data Collections, Data Schema, and Record Collections.