Applies to Pega Platform version 7.2 through 8.4

Rule-Utility-Function (RUF) issues typically surface with the following error messages:

UnresolvedAssemblyError No candidates found

UnresolvedAssemblyError NullPointerException

Failed to compile rule, RUF Error Unsupported Node Type

Failed to compile rule, pega_rulesengine_utilities.java

PegaEL-InvalidExpression No suitable instance found or No candidate found

For each error, this article describes the symptoms, provides techniques for diagnosing the problem (root cause analysis), and offers solutions.

UnresolvedAssemblyError No candidates found

A runtime error where an UnresolvedAssemblyError gets thrown from generated code is frequently reported. This exception is hardcoded into the generated code and is caused by the system being unable to resolve a RUF at rule assembly time. Any rule assembled with this exception can leave the system in an unstable state. If your issue matches any of the symptoms described below, Pega has delivered corrections for Pega 7.31 and Pega 7.4 in the form of hotfixes and in all Pega 8 releases. See Solutions for the hotfixes and patch releases as well as the alternative local change and preventative measures when hotfixes and upgrades are not feasible for your enterprise. 

Symptoms

Root Cause Analysis

Solutions

Symptoms

The following symptoms are typical of the error, UnresolvedAssemblyError No candidates found.

• After performing an Import, you see an unexpected error when doing any action in Pega, usually upon first logging in to your application. The logs show UnresolvedAssemblyError of a RUF.
• You are able to use a system of one node successfully, usually on the node where the Import was done, but it is failing for all other nodes.
• You notice that the system is behaving abnormally, and you see error messages in PegaRULES.log similar to the following example:

Caused by: com.pega.dsm.dnode.api.ExceptionWithInputRecord: com.pega.pegarules.pub.generator.UnresolvedAssemblyError: 1789133548§GetCBSACodeFromIP§PegaEL-InvalidExpression   

No candidates found [possible function name, ruleset/version or number of parameter problem] @.GetCBSACodeFromIP(tools,.IPAddress)

Root Cause Analysis

Use the following approach to isolate the root cause of the problem and provide information to Global Client Support (GCS) in your support case if the Solutions do not work for you.

1. To diagnose this issue, you must have a reliable way to reproduce the error. This could be as simple as running a rule manually, running a case rule, or performing an Import.
2. Then you need to force the reassembly of the Rule calling the RUF. Before re-assembly, you need to delete the current assembly, following these steps:
   
   a. To find the rule to reassemble, refer to the original error from the logs. In the logs, look for a stack trace similar to the following example:
   
   Caused by : com.pega.dsm.dnode.api.ExceptionWithlnputRecord : com.pega.pegarules.pub.generator.UnresolvedAssemblyError : 1789133548§GetCBSACodeFromIP§PegaEL-InvalidExpression No candidates found [possible function name, ruleset/version or number of parameter problem] @.GetCBSACodeFromIP(tools,.IPAddress) at com.pega.dsm.dnode.api.dataflow.DataFlowStage$StageInputSubscriber.onNext(DataFlowStage.java : 361) ... 72 more Caused by: com.pega.pegarules.pub.generator.UnresolvedAssemblyError: 1789133548§GetCBSACodeFromIP§PegaEL-InvalidExpression No candidates found [possible function name, ruleset/version or number of parameter problem] @.GetCBSACodeFromIP(tools,.IPAddress) at com.pega.pegarules.priv.FUAUtil.throwUnresolvedAssemblyError(FUAUtil.java:426) at com.pegarules.generated.model.ra_model_getbranchandcbsadetails_59ccb5dell694c09f86e09b7c7c82f81.when_l(ra_model_getbranchandcbsadetails_59ccb5dell694c09f86e09b7c7c82f81.java : 107)at com.pegarules.generated.model.ra_model_getbranchandcbsadetails_59ccb5dell694c09f86e09b7c7c82f81.perform(ra_model_getbranchandcbsadetailS_59ccb5dell694c09f86e09b7c7c82f81.java: 61)
   
   b. Observe that the Data Transform rule ra_model_getbranchandcbsadetails_59ccb5de11694c09f86e09b7c7c82f81 is encountering an error when calling RUF GetCBSACodeFromIP. Therefore, you will reassemble the data transform ra_model_getbranchandcbsadetails_59ccb5de11694c09f86e09b7c7c82f81. 
   
   Also provide the assembled java of the data transform rule by running the activity pyExtractCode and provide the fully qualified Java class name: 
   com.pegarules.generated.model.ra_model_getbranchandcbsadetails_59ccb5de11694c09f86e09b7c7c82f81
   
   c. To force reassembly, follow the steps in UnresolvedAssemblyError NullPointerException, Solution: Local Change to delete the current assembly. If the calling rule is a rule assembled by Application-Based Assembly (ABA), for example, a Stream, Harness, or Section rule, then submit a support case for GCS to seek assistance from the product engineering team to force reassembly.
    
3. After you have deleted the assembled rule either by Admin Studio or the System Management Application (SMA) for earlier releases, set the logger RUFReferenceHelper to DEBUG. 
4. Then choose an option from Step 1 to reproduce the error.
5. After you have reproduced the error, submit a support case, either the one you might have created in Step 2c or a new support case, and attach the full PegaRULES.log file that results from Steps 3 and 4.

Solutions

The best practice is to update or upgrade to the latest Pega Platform release.

If this is not possible, apply the hotfix or update or upgrade to a Pega Platform Patch Release that is feasible for your enterprise.

As a last resort, perform the local change.

Hotfixes and Platform Patch Releases

Hotfixes, Pega Platform Patch Releases, or upgrades to major Pega Platform releases resolve most instances of UnresolvedAssemblyError. Refer to the following table to determine which solution works for the Pega Platform release that you are using. 
                                            

If you request and install one of the hotfixes identified in the table above and the hotfix does not resolve your problem, create a new support case.

Be sure to attach all the required artifacts (logs, screenshots, steps to reproduce documents, and so on) to your support case to expedite root cause analysis and resolution by GCS.

Local Change

To resolve UnresolvedAssemblyError No candidates found, restart the application server on all nodes of your Pega deployment.

This is the most reliable way to resolve this issue because restarting the server ensures that the LibraryMetadata of all Rule-Utility-Library rules are consistent across all nodes.

Prevention

To prevent UnresolvedAssemblyError No candidates from occurring in your production environment, try one of the following suggested approaches:

• Revalidate and Save the rulesets included in the RAP after each import.
  Doing this immediately after each import should prevent the error. You do not have to wait until the error appears to perform Revalidate and Save.
  This option is the easier than the second option.
  See About the bulk Revalidate and Save tool.
• Specify the exact ruleset version in your application before the import and update it after the import.
  For example, if you are importing a RAP that contains rules only in RulesetX. Then, in the target application of your import, specify the current highest ruleset version for RulesetX, for example, RulesetX:01-01-01.
  When the system finishes importing the rules to a new RulesetX version, for example, RulesetX:01-01-02, you can update the application to use that version.
  This option is a technique that has been used by other users; however, it is a manual process.

UnresolvedAssemblyError NullPointerException

Symptoms

Root Cause Analysis

Solutions: Local Changes

Symptoms

A rule calling an RUF throws an UnresolvedAssemblyError caused by an NPE. Typically, this error is not immediately obvious and can manifest in many ways. For example, you might see that certain functions are not responding correctly, or you might not be able to log-in or create a case. Then you see an error in PegaRULES.log, similar to this example:

2019-09-30 20:18:26,274 [Flow.Default-Pulse:0] [  STANDARD] [                    ] [                    ] (ow.service.DataFlowServiceImpl) ERROR   - Could not apply node failure policy. Will fail the run [Test]

com.pega.pegarules.pub.generator.UnresolvedAssemblyError: Error occurred trying to parse the expression and augmenting the code: java.lang.NullPointerException

    at com.pega.pegarules.priv.FUAUtil.throwUnresolvedAssemblyError(FUAUtil.java:427) ~[prpublic.jar:?]

    at com.pegarules.generated.trigger.ra_action_pzcaptureworkobjectsforautomaticcleanup_0f60d7c3a3474ba675d872e00fc5461d.perform(ra_action_pzcaptureworkobjectsforautomaticcleanup_0f60d7c3a3474ba675d872e00fc5461d.java:82) ~[?:?]

    at com.pega.pegarules.session.internal.mgmt.Executable.doAction(Executable.java:2204) ~[prprivate.jar:?]

Root Cause Analysis

Use the following approach to isolate the root cause of the problem and provide information to Global Client Support (GCS) in your support case if the Solutions do not work for you.

Given the stack trace above, the rule calling the RUF is com.pegarules.generated.trigger.ra_action_pzcaptureworkobjectsforautomaticcleanup_0f60d7c3a3474ba675d872e00fc5461d.

This rule should be provided to pyExtractCode.

To get the generated code, run Code-Pega-:pyExtractCode in Pega-RulesEngine:08-01-01 and provide the fully qualified Java class name of the rule calling the RUF.

Additional logging captures the cause behind the NPE directly in the generated code itself. To find this, select Ctrl+S in the generated code for FUAUtil.throwUnresolvedAssemblyError. Above that, you should see a comment block with a detailed error stack trace similar to the example shown above.

If the generated code does not display a stack trace as a comment block similar to the example shown above, then additional log gathering is required to capture the error at the time of the bad rule assembly.

Follow these steps to perform additional logging:

1. Find when the problem rule was assembled by running the following query:

   select * from pr_assembledclasses
   where pzclass = '[java class name of the problem rule]' (no package name)

   Example:

   '[ra_action_pzcaptureworkobjectsforautomaticcleanup_0f60d7c3a3474ba675d872e00fc5461d]'

2. Get the timestamp from the pzlastmodified column.
3. Ensure that the PegaRULES.log file contains log events from that timestamp.
   At the time the NPE is thrown, you should see error logs from Antlr3TranslateExpression.
4. Include all the data artifacts from the previous steps in your support case.

Solutions: Local Changes

Forcing the reassembly of the rule calling the RUF can resolve UnresolvedAssemblyError caused by an NPE.

Below, the first two procedures work for VTable Assembled rules only.

The third procedure works for Application-Based Assembly (ABA) rules such as Stream, Harness, or Section rules.

Local Change for Pega 8 releases

If you are using a Pega 8 release, perform the following steps to force the reassembly of VTable Assembled rules:

1. In Admin Studio, click Resources > APIs > System Management > caches and select the following POST API:
    /nodes/all/caches/vtable/rule_types/{pxobjclass}/instances/{pxinsid}/reassemble
2. Provide the rule's pxObjClass and pxInsID.

Example:

pzcaptureworkobjectsforautomaticcleanup

              pxObjClass: Rule-Declare-Trigger

              pxInsID: !PZCAPTUREWORKOBJECTSFORAUTOMATICCLEANUP

Local Change for Pega 7 and earlier releases

If you are using a release prior to Pega 8, force reassembly of VTable Assembled rules using the System Management Application (SMA).

You will need to provide the rule’s pxObjClass and pxInsID.

Follow the procedure in SA-24578 Unresolved Assembly error when closing work objects.

Local Change for forcing reassembly of ABA-based rules

If the badly assembled rule is an Application-Based Assembly (ABA) rule such as Stream, Harness, or Section, you must have database access to reassemble the rule.

1. Delete the rule from pr_assembledclasses by running a query similar to the following example:
   Be sure to specify the rule name between the percent (%) symbols.
   
   delete from pr_assembledclasses where pzclass like '%[Enter rule name here]%'
2. After the bad class is deleted from pr_assembledclasses, restart the application server on all nodes of your Pega deployment. This is required because the badly assembled rule is already cached in memory for most nodes in the cluster.

Failed to compile rule, RUF Error Unsupported Node Type

Symptoms

Root Cause Analysis

Solution: Local Change

Symptoms

This issue usually occurs when upgrading from Pega 7 to Pega 8. After the upgrade completes, the following error messages appear in the PegaRULES.log file:

SEVERE: Problem during method invocation (main)

and

ERROR   - Failed to compile rule: /com/pegarules/generated/pega_rules_utilities.java

ERROR   - Error compiling: com/pegarules/generated/pega_rules_utilities; see class's compile log file.

Root Cause Analysis

Use the following approach to isolate the root cause of the problem and provide information to Global Client Support (GCS) in your support case if the Solution does not work for you.

Try to reproduce the issue using the following approach:

1. Enable DEBUG loggers for LibLibraryDef.
   
   After you have reproduced the issue, you should attach the PegaRULES.log file, with LibLibraryDef set to DEBUG logging,  to your support case.
   
   It is important to capture the errors with this DEBUG log enabled. However, it is also likely that this issue will leave the system non-functional and prevent access to Dev Studio or Admin Studio. Therefore, if you recently encountered this issue in your Pega 8 system, you should set up a log-category rule so that you can enable the DEBUG loggers for LibLibraryDef without needing to modify the prlog4j2.xml file. For more information on creating log-category rules, see Log categories.
2. Specify the prconfig.xml being used. Make sure that fua/enableSkipPreviousPegaFunction is not set to false.
3. To understand the compilation failure, GCS needs access to the compilation logs. Attach the compilation logs to your support case. In the errors shown above, pega_rules_utilities has failed to compile. Therefore, generate and attach the pega_rules_utilities.log file to your support case.
4. Determine whether the compilation failure is caused by an attempt to compile a Pega 7 RUF in a Pega 8 system:
   
   Look at the RUF class name:
   
   [rulename]_[version]_[hash])
   
   If the version starts with 07XXXX and you are using Pega 8, then this Pega 7 version qualifier confirm that this is the issue. See the following examples errors:
   
   1. ERROR in /com/pegarules/generated/p_071035_6932506424462612470.java (at line 114)
   
   boolean appicableNodeTypesListContainsCurrentNodeType = aNodeClassification.isDefinedInApplicableNodeTypes(nodeType);                                                                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   The method isDefinedInApplicableNodeTypes(String) is undefined for the type NodeClassification
   
   2. ERROR in /com/pegarules/generated/pzRemoveUnsupportedNodeTypes_071035__3445482784356381704.java (at line 127)
   
    boolean appicableNodeTypesListContainsCurrentType = aNodeClassification.isDefinedInApplicableNodeTypes(nodeType);                                                                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   The method isDefinedInApplicableNodeTypes(String) is undefined for the type NodeClassification
   ----------
   2 problems (2 errors)
   Compile failed.
5. After reproducing this issue using the procedure above, be sure to attach the following artifacts to your support case:

• PegaRULES.log file with LibLibraryDef set to DEBUG logging
• The appropriate compilation log files

Solution: Local Change

If an error is caused by attempting to compile a Library rule that references a Pega 7 RUF in a Pega 8 system (Root Cause Analysis Step 4), then deleting that Pega 7 RUF from the rulebase solves the problem.

1. Make sure that you have database access to run the database queries required for this solution.
2. Examine the error messages to see that the second error statement indicates that the system fails to compile the RUF pzRemoveUnsupportedNodeTypes_071035_3445482784356381704.java, which is a Pega 7 RUF because the class name shows the version 07-10-35.
3. Search for this problematic RUF in the database using the following query:
   
   select * from pr4_rule_library
   where pymethodname = 'pzRemoveUnsupportedNodeTypes'
   and pxobjclass = 'Rule-Utility-Function'
   and pyrulesetversion = '07-10-35'
   delete from pr4_rule_library
   where pymethodname = 'pzRemoveUnsupportedNodeTypes'
   and pxobjclass = 'Rule-Utility-Function'
   and pyrulesetversion = '07-10-35'
4. Carefully inspect the query results and confirm that the records displayed match the RUF in the error message.
5. Then delete those rules by replacing select * with delete
   
   delete from pr4_rule_library
   where pymethodname = 'pzRemoveUnsupportedNodeTypes'
   and pxobjclass = 'Rule-Utility-Function'
   and pyrulesetversion = '07-10-35'

Failed to compile rule, pega_rulesengine_utilities.java

Symptoms

Errors

Root Cause Analysis

Solutions

Symptoms

Users report Pega platform upgrade failures that are caused by Rule Utility Function compile errors.

If upgrades do succeed, many areas of the Pega deployment do not work as expected, resulting in system outage.

Errors

[java] 2020-03-26 10:53:55,118 [ 8819c2412fb1] [ STANDARD] [ ] [ ] ( pega.jsr199.Jsr199Bridge) ERROR - Failed to compile rule: /com/pegarules/generated/pega_rulesengine_utilities.java

[java] 2020-03-26 10:53:55,118 [ 8819c2412fb1] [ STANDARD] [ ] [ ] ( pega.jsr199.Jsr199Bridge) ERROR - Failed to compile rule: /com/pegarules/generated/pega_rulesengine_utilities.java

16:23:55

[java] 2020-03-26 10:53:55,467 [ 8819c2412fb1] [ STANDARD] [ ] [ ] (ary.LibraryFunctionUtilityImpl) ERROR - Error compiling: com/pegarules/generated/pega_rulesengine_utilities; see class's compile log file

Root Cause Analysis

In Pega 8.1 through Pega 8.4, some standard Rule Utility Functions (RUFs) were changed to leverage newer versions of third-party libraries. Those third-party libraries contain breaking API changes, so that code written against older versions of the third-party library no longer compiles.

In the Pega Infinity^TM versions of these Rule Utility Functions, we have adopted the new library APIs.  Yet, older versions of the Functions cannot work. Therefore, the Pega platform filters out those older versions.

This problem occurs when this filtration logic is not working correctly.

Solutions

When this problem occurs, there is severe functional degradation. Therefore, taking corrective action is critical.

Choose the corrective action that best meets the needs of your enterprise:

• Update or upgrade to a Pega Platform Patch Release. (Best Practice, Strongly Recommended)
• Apply one of the available hotfixes. (Pega 8.2.2 and Pega 8.3.1)
• Perform the local change. (Not Recommended)

Issue resolved in Pega Platform releases or by hotfixes

Upgrading your system is the best solution.

Refer to the Pega Upgrade Center.

Contact Global Client Support (GCS) if you need assistance in upgrading your system.

Local Change

The local change described here has risks associated with it. Use it with extreme care. Contact GCS if you are uncertain about how to apply the local change or do not completely understand the consequences of the database queries.

If you cannot update or upgrade your Pega deployment or apply a hotfix, explicitly remove all the older Pega 7 major version RUFs that are part of the rulesets in the PegaRULES application.

Do this by manually deleting the older RUFs from Pega-* rulesets that have versions 07-10-xx. 

1. Use the following example Select query to find the RUFs you need to delete:
   Select * FROM [rules schema].pr4_rule_library WHERE (PYRULESETVERSION is not null AND PZRULESETVERSIONMAJOR < 8) AND (PXOBJCLASS = 'Rule-Utility-Function') AND ((PYRULESET LIKE 'Pega-%' OR PYRULESET = 'DMSample') AND PYRULESET NOT LIKE '%Branch%');
2. Review the results of the query.
   
   Review these results closely.
   Ensure that this list does NOT contain Rulesets whose names start with Pega- but which are part of some Industry Application product built on the Pega Platform.
3. When you are satisfied with the Select query results, change the query to Delete:
   Delete * FROM [rules schema].pr4_rule_library WHERE (PYRULESETVERSION is not null AND PZRULESETVERSIONMAJOR < 8) AND (PXOBJCLASS = 'Rule-Utility-Function') AND ((PYRULESET LIKE 'Pega-%' OR PYRULESET = 'DMSample') AND PYRULESET NOT LIKE '%Branch%');
4. Commit the Delete changes.
5. Restart the affected application server nodes.

PegaEL-InvalidExpression No suitable instance found or No candidates found

Symptoms

Root Cause Analysis

Solution: Local Change

Symptoms

This error can occur across a broad range of features. You might see it when sending an HTTP request or when performing any action in the UI. The system cannot resolve an RUF signature against the current user's application ruleset list.

An error message with No suitable instance found might look like this example:

Invalid expression or reference: No suitable instance found [seeking] @(Pega-RULES:Utilities).LengthOfPageList(ClipboardProperty) [candidate functions are]

An error message with No candidates found might look like this example:

Invalid expression or reference: No candidates found [possible function name, ruleset/version or number of parameter problem] Invalid expression or reference: No suitable instance found [seeking]  @&#40;Pega-RULES:ExpressionEvaluators&#41;.compareTwoValues&#40;boolean,String,*Unknown&#41; [candidate functions are]

You might also see FirstUseAssembly errors such as FUAInstance-CompileFailed.

Root Cause Analysis

Use the following approach to isolate the root cause of the problem and provide information to Global Client Support (GCS) in your support case if the Solution does not work for you.

1. Enable DEBUG logging on ContextUtils and RUFReferenceHelper.
2. After you set the loggers to DEBUG, reproduce the issue by triggering one of the symptoms.
   
   This helps determine the context of the error better by identifying the application's ruleset list and the code path taken to resolve the RUF signature.
3. Generate the code of the rule calling the RUF.
4. In your support case Description, identify the timestamp for the reproduced problem.
5. Attach the following artifacts to your support case:
   • PegaRULES.log file
   • The generated code

Solution: Local Change

If the RUF is referenced in shorthand notation without the library, you can private-edit the rule and fully qualify the RUF to resolve the error.

For example, if the RUF is referenced as @RUF(), try specifying its library:  @(ARuleSet:ALib).RUF()

For more information on how to call RUFs, see Call-Function.

Related Content

Rules management

Using the Revalidate and Save tool