When creating or maintaining applications, unexpected behavior can occur. Troubleshooting is the process of finding and fixing these problems. Before working through the steps below manually, try describing the issue to the Build Agent in the Module Builder. It can often identify the cause of common configuration problems quickly.
For especially complex issues, contact support.unqork.com.
Basic Steps of Troubleshooting
Troubleshooting begins when unexpected behavior displays in an application. The starting point can take different forms: an error message, a problem in a downstream system, or something displaying incorrectly. Whatever the issue, it differs from how the application should run.
The basic steps of troubleshooting are:
-
Investigate and Replicate: Understand the context of the unexpected behavior and, if possible, recreate the issue.
-
Isolate: Narrow down the search to isolate the cause.
-
Terminate: Once the cause is identified, fix it.
Use Module Outline in the Module Builder to help diagnose common configuration issues.
Investigate and Replicate
The first step is to understand the system and what is failing. Investigate the unexpected behavior before looking for the root cause. This is especially challenging if the person reporting the issue lacks specific details.
Think of the natural that could have led someone to the error. Consider the end-user's mindset and how they encountered the issue. Following the flow of the application or module often leads to the page with the error.
Try different combinations of events and values. Note results and observations.
Consider the following questions when investigating unexpected behavior:
-
Do I understand the issue?
-
Do I know what is happening?
-
What series of events led up to this unexpected result?
-
Do I understand what is supposed to happen based on the configuration or requirements?
-
Which environment is the end-user in?
-
What role does the end-user have?
-
Are they using test data or Production data?
Confirming that the failure occurs consistently and understanding its context is essential before moving on.
Be careful when replicating a behavior. Only replicate the issue if doing so will not cause problems in production.
Once the issue is described and replicated, move on to isolating the unexpected behavior.
Isolate
The next step is to narrow down the location of the issue. The key question is: at what point does the actual behavior diverge from what is expected?
One effective approach is to divide the module in half. Duplicate the module and remove the second half. If the error persists, the issue is in the first half; if not, check the second. Continue halving until the location is isolated.
With the location identified, isolate individual factors. Check the details of the application's components. If a Calculator component does five calculations, look through each one.
The isolation process can take time. Taking a break or talking through the issue with a teammate can help. Describing the isolated area to the Build Agent can also help surface what is going wrong.
Terminate
Once the cause is identified, fix it. The action could be as simple as changing a yes to a true in a Decisions component, or it could be more complex. If the issue has been investigated and isolated, this step is straightforward.
Avoid getting too attached to one approach when resolving unexpected behavior. If a Decisions component is not resolving the issue, consider whether a Calculator or Initializer component would be a better fit. The Build Agent can also suggest alternative configurations once the cause is known.
After applying a fix, confirm it resolved the issue. Check the data and the page to confirm everything looks as expected. Run the module and repeat the steps from the replication phase. Test different variations to confirm everything still functions as expected.
See Also
- Common Troubleshooting Strategies — common strategies for diagnosing issues in Unqork applications.
- Error Handling in Unqork — creating pop-up messages for network errors at runtime.
- Understanding Service Logs — reading and querying Unqork service logs.
Changelog
| Date | Change |
|---|---|
| 2026-07-16 | Initial publication. |