Troubleshooting Versioned Applications

Troubleshooting versioned applications mirrors traditional Unqork troubleshooting, but introduces version awareness. Learn how to troubleshoot effectively in a versioned context, balancing best practices with real-world team behaviors using the sections below.

Core Troubleshooting Principles

Unqork’s troubleshooting framework follows foundational steps. These steps apply to both versioned and unversioned applications, but versioning introduces unique considerations.

1. Investigate and Replicate: Understand the unexpected behavior and attempt to reproduce it safely.

   • What is the issue?

   • What should the application be doing?

   • What environment and role are involved?

2. Isolate: Confirm the location of the issue. Use strategies like separating the module or checking component logic to pinpoint the root cause.

3. Terminate: Resolve the issue. Confirm the fix by retesting and validating.

How Versioning Affects Troubleshooting

Unlike regular Unqork applications, Creators must be aware of the different versions of an application and how they are applied to each environment.

Environment Awareness

In a versioned application, the same module might exist in multiple environments with different version states. Failing to align the troubleshooting effort with the correct version can lead to misdiagnosis or wasted effort.

Troubleshoot by identifying the following:

• Which version is deployed in Production?

• Is that version also set as the default?

• Was a specific version passed using the context parameter?

• If the application has dependencies, what versions of those dependent modules are being executed?

• Are the symptoms occurring in both environments, or only one?

Branching and Editing the Correct  Version

Once the issue is identified, apply the fix to the intended version lineage and avoid overwriting unrelated changes.

The correct version must meet the following requirements:

• Branched for safe editing.

• Modified to address the issue.

• Merged and published if the fix is validated.

Identifying the Executed Version: URL Context and HAR File Capture

When troubleshooting versioned applications, it's essential to determine which version of a module or application was executed during an end-user session. You can achieve this action by passing the module ID and version directly in the URL.

• URLs now carry version context, making it easier to trace which configuration was triggered. For example, when viewing a version application, the URL might contain the following: context=d6914c0c1e631c2b91fec54b2.

• Service logs will reflect this context because back-end systems log incoming requests with full URLs.

In cases where logs do not provide enough clarity, especially during client-side issues or intermittent failures, capturing a HAR (HTTP Archive) file from the browser becomes invaluable. HAR files record all network activity during a session, including:

• The exact URL used (with embedded version info).

• API calls and responses.

• Any failed requests or error codes.

Analyzing the HAR file helps you confirm the module version that was executed. That way, you can correlate it with back-end logs. Using the URL context in logs and HAR file capture can greatly improve accuracy and efficiency during version-related troubleshooting.

Troubleshooting: Incorrect Environment

While best practices dictate troubleshooting in the active development environment, teams might sometimes investigate issues directly in Production or a previous environment if the version exists. Doing so is not ideal in any environment besides Staging because it risks the following scenarios:

• Misinterpreting symptoms due to environment-specific configurations.

• Overlooking version mismatches between environments.

• Accidentally introducing changes if the investigation escalates into debugging or patching.

• Bypassing version control protocols if fixes are applied outside the intended workflow.

Troubleshooting should remain a diagnostic process, focused on understanding what is running and identifying the root cause. Any changes should be routed through proper environments and governance.

Best Practices

Troubleshooting in Unqork is a dynamic, iterative process. By following structured steps and respecting the versioning framework, teams can resolve issues efficiently without compromising application integrity.

Discover general troubleshooting strategies and best practices for Unqork by visiting the Troubleshooting Landing Page.