Fix fallback logic when the agent don't have node handler installed #5461

surajitshil-03 · 2026-01-28T14:18:36Z

Context

This PR addresses a Node.js version fallback issue on platforms where certain Node versions are not available (e.g., win-x86 where Node24 binaries are not shipped). Currently, when a task requests Node24 but the binary doesn't exist on the platform, the agent fails instead of gracefully falling back to an available Node version (Node20 or Node16).

Related repair-item: AB#2351680

Description

Legacy node selection:

Added IsNodeFolderExist() check in GetNodeFolderWithFallback() to detect when Node24/Node20 binaries are missing
Implemented fallback chain: Node24 → Node20 → Node16 when binaries don't exist
Added PublishNodeFallbackTelemetry() to track fallback scenarios
Updated warning messages to indicate platform availability issues

Node selection based on strategy pattern:

Added IsNodeFolderExist() check at the start of each strategy's CanHandle() method
Node20Strategy now handles Node24HandlerData tasks as fallback when Node24Strategy returns null
Node16Strategy now handles both Node24HandlerData and Node20HandlerData tasks as fallback
Added telemetry publishing for fallback scenarios in each strategy
Added appropriate warning messages with architecture information

Risk Assessment (Low / Medium / High)

Medium

Code path sensitivity: Node handler selection is a critical path for all Node-based tasks
Backward compatibility: Existing behavior is preserved when Node binaries exist; fallback only activates when binaries are missing

Unit Tests Added or Updated (Yes / No)

Updated NodeHandlerTestBase.cs to register INodeHandlerHelper mock via SetSingleton, enabling proper testing of Node24 fallback scenarios when the Node24 binary is not available on certain platforms (e.g., win-x86).

Additional Testing Performed

Manually tested the scenario in iwin-x64 machine without node 24 and the fallback is happening as expected:

Change Behind Feature Flag (Yes / No)

Can this change be behine feature flag, if not why?

Tech Design / Approach

In legacy node selection process we have added the IsNodeFolderExist() check which now checks whether the node exist or not before checking for glibc errors.
In strategy pattern selection process we are using the nodehandler info for the higher priority nodes in subsequent/fallback node strategies to fallback properly.

Documentation Changes Required (Yes/No)

No

Logging Added/Updated (Yes/No)

Yes
Debug logs added for fallback decision points (e.g., "[Node24Strategy] Node24 binary not available on this platform, returning null for fallback")

Telemetry Added/Updated (Yes/No)

Yes
New fallback telemetry published via PublishNodeFallbackTelemetry() includes:

RequestedNodeVersion - The originally requested Node version
FallbackNodeVersion - The version being used instead
FallbackReason - Why fallback occurred (NodeNotAvailable, GlibCError)
Architecture - Process architecture (x86, x64, ARM64)
, OSName, OSVersion - Platform information
Strategy - Which strategy handled the fallback
JobId, PlanId, AgentName, AgentVersion, IsSelfHosted

Rollback Scenario and Process (Yes/No)

Revert to older agent versions or revert the changes in the code and release a new agent.

Dependency Impact Assessed and Regression Tested (Yes/No)

All impacted internal modules, APIs, services, and third-party libraries are analyzed.
Results are reviewed and confirmed to not break existing functionality.

surajitshil-03 · 2026-01-28T14:22:15Z

/azp run

azure-pipelines · 2026-01-28T14:22:28Z

Azure Pipelines successfully started running 1 pipeline(s).

surajitshil-03 · 2026-01-28T17:45:45Z

/azp run

azure-pipelines · 2026-01-28T17:45:59Z

Azure Pipelines successfully started running 1 pipeline(s).

sanjuyadav24 · 2026-01-29T03:37:54Z

src/Agent.Worker/NodeVersionStrategies/Node16Strategy.cs

            }

+            // Handle Node24 tasks as fallback when Node24Strategy and Node20Strategy returned null
+            if (hasNode24Handler)


why is this required here?

sanjuyadav24 · 2026-01-29T03:39:21Z

src/Agent.Worker/NodeVersionStrategies/Node20Strategy.cs

+            return result;
+        }
+
+        private bool IsNodeFolderExist(string nodeFolderName, IExecutionContext executionContext)


shouldn't this be part of some helper class as this is required in all strategy classes

used the already implemented method for checking existence of node folder

sanjuyadav24 · 2026-01-29T03:39:37Z

src/Agent.Worker/NodeVersionStrategies/Node20Strategy.cs

+            return File.Exists(nodePath);
+        }
+
+        private void PublishNodeFallbackTelemetry(IExecutionContext executionContext, string requestedNodeVersion, string fallbackReason, TaskContext context, string fallbackNodeVersion = null)


this should also be part of some helper class

Used the telemetry class used in the main orchestrator file

surajitshil-03 · 2026-01-29T09:32:00Z

/azp run

azure-pipelines · 2026-01-29T09:32:13Z

Azure Pipelines successfully started running 1 pipeline(s).

…er class

surajitshil-03 · 2026-01-29T09:58:49Z

/azp run

azure-pipelines · 2026-01-29T09:59:02Z

Azure Pipelines successfully started running 1 pipeline(s).

sanjuyadav24 · 2026-01-29T11:38:28Z

src/Agent.Worker/Handlers/NodeHandler.cs


    [ServiceLocator(Default = typeof(NodeHandlerHelper))]
-    public interface INodeHandlerHelper
+    public interface INodeHandlerHelper : IAgentService


why is this added here?

Checking this change if we can implement it in some other way.

Made the changes but to avoid the testcases to fail I have created a new interface in the file INodeExistenceChecker.cs in which we have defined the method to check the node folder exists or not. Like in this way when the test cases will call this method then this will return true always because the test cases always expect to return true for node folder availability check.

… during Node24 strategy

surajitshil-03 · 2026-01-29T13:59:48Z

/azp run

azure-pipelines · 2026-01-29T14:00:01Z

Azure Pipelines successfully started running 1 pipeline(s).

surajitshil-03 added the enhancement label Jan 28, 2026

sanjuyadav24 reviewed Jan 29, 2026

View reviewed changes

surajitshil-03 marked this pull request as ready for review January 29, 2026 09:55

surajitshil-03 requested review from a team as code owners January 29, 2026 09:55

surajitshil-03 added 7 commits January 29, 2026 15:27

Fixing fallback

09faafc

Fixing fallback

c624f05

Fixing the fallback logic in new node selection strategy

94fc3c3

Reverting changes in node16/20 strategy and making new telemetry help…

1384df8

…er class

Minor changes

dd30f83

Refactoring code and removing duplicate telemetry helper class

8cc8b96

Fixing the test failures

950edf2

surajitshil-03 force-pushed the users/surajitshil/fixFallBack branch from 39e519c to 950edf2 Compare January 29, 2026 09:58

sanjuyadav24 reviewed Jan 29, 2026

View reviewed changes

Removing the extend to IAgentService and adding constructor injection…

8dc6c30

… during Node24 strategy

Fix fallback logic when the agent don't have node handler installed #5461

Are you sure you want to change the base?

Fix fallback logic when the agent don't have node handler installed #5461

Conversation

surajitshil-03 commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Description

Risk Assessment (Low / Medium / High)

Unit Tests Added or Updated (Yes / No)

Additional Testing Performed

Change Behind Feature Flag (Yes / No)

Tech Design / Approach

Documentation Changes Required (Yes/No)

Logging Added/Updated (Yes/No)

Telemetry Added/Updated (Yes/No)

Rollback Scenario and Process (Yes/No)

Dependency Impact Assessed and Regression Tested (Yes/No)

Uh oh!

surajitshil-03 commented Jan 28, 2026

Uh oh!

azure-pipelines bot commented Jan 28, 2026

Uh oh!

surajitshil-03 commented Jan 28, 2026

Uh oh!

azure-pipelines bot commented Jan 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

surajitshil-03 commented Jan 29, 2026

Uh oh!

azure-pipelines bot commented Jan 29, 2026

Uh oh!

surajitshil-03 commented Jan 29, 2026

Uh oh!

azure-pipelines bot commented Jan 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

surajitshil-03 commented Jan 29, 2026

Uh oh!

azure-pipelines bot commented Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

surajitshil-03 commented Jan 28, 2026 •

edited

Loading