(fix) O3-4681: Handle missing subforms gracefully to prevent null crash by vivektarun · Pull Request #703 · openmrs/openmrs-esm-form-engine-lib

vivektarun · 2026-03-15T09:33:27Z

Summary

Fixes a crash where forms containing subform pages (isSubform: true)
referencing a form that does not exist on the backend threw:

TypeError: Cannot read properties of null (reading 'markdown')

making the entire form unusable with a white screen error.

Related Issue

Fixes O3-4681

Root Cause

When fetchOpenMRSForm returned null for a missing subform:

Promise.all in loadSubForms crashed the entire form load
refinedFormJson became null but no null guard existed
Multiple components tried to access .sections on subform
pages which have no sections property

Changes

File	Change
`useFormJson.ts`	`Promise.allSettled` + null guards
`form-engine.component.tsx`	null guard for `refinedFormJson`
`encounter-form-processor.ts`	null guard for `page.sections`
`page.renderer.component.tsx`	`InlineNotification` for missing subform
`common-utils.ts`	`Array.from(page.sections ?? [])`
`useFormJson.test.ts`	new test for missing subform scenario

Before

Screen.Recording.2026-03-15.at.12.52.52.AM.1.mov

White screen crash
TypeError: Cannot read properties of null (reading 'markdown')
Form completely unusable

After

Screen.Recording.2026-03-15.at.2.48.48.PM.mov

Parent form renders correctly
Missing subform page shows helpful error:
"Subform could not be loaded. Please verify the form name
is correct and that it is published."
Other pages render normally
Helpful console message logged

Screenshots

Tests Passing

How to Test

Open form-builder
Create a new form
Paste this schema in the schema editor:

{
  "name": "Test Subform Parent",
  "version": "1",
  "published": false,
  "retired": false,
  "referencedForms": [],
  "allowUnspecifiedAll": true,
  "pages": [
    {
      "label": "Lab Order",
      "isSubform": true,
      "subform": {
        "name": "HMIS LAB 001:General Laboratory Test"
      }
    },
    {
      "label": "Main Section",
      "sections": [
        {
          "label": "Test Section",
          "isExpanded": true,
          "questions": [
            {
              "label": "Notes",
              "type": "obs",
              "id": "notes",
              "questionOptions": {
                "rendering": "textarea",
                "concept": "160632AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
              }
            }
          ]
        }
      ]
    }
  ]
}

Click Render Changes
Confirm:
- ✅ No crash
- ✅ Lab Order page shows red error notification
- ✅ Main Section renders with Notes field
- ✅ Console shows helpful error message

Checklist

Fixes the reported crash
Unit test added for missing subform scenario
All existing tests pass (7/7)
Tested locally against dev3.openmrs.org
PR title follows conventional commit format
No breaking changes to existing functionality

Problem: When a form contained a subform page (isSubform: true) referencing a form that does not exist on the backend, the form engine crashed with: TypeError: Cannot read properties of null (reading 'markdown') making the entire form unusable. Changes: - useFormJson.ts: Replace Promise.all with Promise.allSettled in loadSubForms so a single missing subform does not crash the parent form. Add null guard in updateFormJsonWithSubForms. - form-engine.component.tsx: Add null guard for refinedFormJson before rendering to prevent crash when form loading fails. - encounter-form-processor.ts: Add null guard for page.sections in prepareFormSchema and processFields to safely skip subform pages that have no sections. - page.renderer.component.tsx: Show an InlineNotification error message when a subform page fails to load instead of crashing. Added page.sections ?? [] guard to safely handle missing sections. - common-utils.ts: Use Array.from(page.sections ?? []) to prevent 'undefined is not iterable' crash on subform pages. - useFormJson.test.ts: Add test case verifying that the parent form loads correctly and logs an error when a subform cannot be found. Before: Form crashed with null reference error, white screen shown. After: Parent form renders correctly. Missing subform page shows a helpful error: 'Subform could not be loaded. Please verify the form name is correct and that it is published.'

samuelmale · 2026-03-16T08:21:50Z

Thanks for working on this @vivektarun! I think beyond this PR, we should ensure that a subform doesn't create its own Encounter or Visit.

vivektarun · 2026-03-16T09:56:14Z

Hi @samuelmale, thank you for the feedback!

I understand the concern about subforms creating their own Encounter. Let me share my understanding of the problem and the proposed fix.

Current wrong behaviour

When a subform is loaded and the doctor submits the form, FormProcessorFactory is instantiated twice — once for the parent form and once for the subform. The subform instance has no reference to the parent's encounter, so it calls saveEncounter() independently and creates a brand new Encounter in the database. This results in two separate Encounter records for a single form submission — one holding the parent form observations and one holding the subform observations. When the doctor opens the form next week to edit, the form loads only the parent encounter and the subform fields appear empty because their observations are stored under a completely different encounter that the form has no way of finding.

Proposed correct behaviour

The subform should never create its own Encounter. Instead:

form-renderer.component.tsx should pass the parent form's existing encounter (context.domainObjectValue) down to the subform's FormProcessorFactory as a prop
form-processor-factory.component.tsx should accept this parentEncounter prop and inject it into the subform's processorContext as domainObjectValue
encounter-form-processor.ts should detect that isSubform is true and domainObjectValue already exists, and skip creating a new encounter — instead saving all subform observations under the parent encounter's uuid

This way one single Encounter holds all observations from both the parent form and the subform, and editing works correctly next time.

I have attached three diagrams below showing the wrong flow, the correct flow, and the database state comparison:

A few questions before I start coding this:

Is this the right approach or does the team have a different design in mind for how subforms should share the parent encounter?
Should this be addressed in this same PR or opened as a separate issue since it is a different concern from the null crash fix?
Is there an existing pattern in the codebase where a child processor shares a parent's domain object that I can reference?

Happy to implement this if the approach looks correct. Thank you!

ibacher

Thanks @vivektarun. I think most of my remarks are about comments here.

ibacher · 2026-03-16T14:32:24Z

+      // Guard: skip subform pages that have no sections
+      // (subform failed to load or is still a reference placeholder)


This comment is inaccurate as there's nothing in the code as written that makes this applicable to subforms.

ibacher · 2026-03-16T14:33:25Z

 }

-export default I18FormEngine;
+export default I18FormEngine;


Suggested change

export default I18FormEngine;

export default I18FormEngine;

ibacher · 2026-03-16T14:34:23Z

      !isTrue(page.isHidden) &&
      page.subform?.form?.encounterType === formJson.encounterType
    ) {
+      // Guard: skip if subform.form failed to load (is null/undefined)


I don't think this comment is particularly helpful

ibacher · 2026-03-16T14:34:36Z

+ * @param subForms - Array of loaded subform schemas
+ */
 function updateFormJsonWithSubForms(formJson: FormSchema, subForms: FormSchema[]): void {
+  // First populate successfully loaded subforms


ibacher · 2026-03-16T14:35:01Z


+/**
+ * Updates the parent form JSON with the loaded subforms.
+ * Includes a null guard to safely skip any undefined subform entries.


Please remove this second line.

ibacher · 2026-03-16T14:39:44Z

+    // Build a raw parent form that references a subform that does not exist on the backend.
+    // This simulates the exact scenario from O3-4681 where a subform name is wrong or
+    // the subform has not been published yet on the target server.


The first line of this comment is ok. The rest of it should be excised.

ibacher · 2026-03-16T14:40:08Z

+              // Show a clear error message when the subform could not be loaded.
+              // This helps admins/developers immediately understand what went wrong
+              // instead of seeing a blank page or a cryptic crash.


Does this comment explain something a programmer wouldn't already understand?

Further note that although you may want to make this visible to admins or developers, like most error messages, this is probably mostly going to be seen by users who are neither. It's likely more helpful to say something like "Contact your system administrator."

You are right on both points. The comment is self-evident from the code, so that I will remove it. I will also update the message to say something like 'Contact your system administrator' since end users will mostly see this.

ibacher · 2026-03-16T14:42:11Z

+                subtitle={t(
+                  'subformLoadErrorMessage',
+                  'The subform "{{subformName}}" could not be found on this server. Please verify the form name is correct and that it is published.',
+                  { subformName: page.subform?.name },


Is 'The subform "undefined" could not be found on this server.' a message we want to display?

No, that is a bad user experience. I will add a guard so that if page.subform?.name is undefined it falls back to a generic message without showing the word undefined.

ibacher · 2026-03-16T14:42:42Z

+      // Guard: subform pages have no sections — return empty array
+      // so the rest of the component renders safely


This comment should be excised.

ibacher · 2026-03-16T14:43:19Z

+  // If this page is a subform page but the subform failed to load,
+  // show a helpful inline error instead of crashing.


I don't know that this comment is helpful.

- remove unhelpful inline comments - update formSessionIntent JSDoc - include subform name in error log - use type predicate instead of cast - fix undefined in error message - update error message for end users

vivektarun · 2026-03-16T19:45:01Z

Hi @ibacher, thank you for the detailed review! I have addressed all the comments. Here is a summary of the changes made:

Removed all unhelpful inline comments that were self-evident from the code itself.
Updated the formSessionIntent JSDoc in both loadFormJson and loadSubForms to explain that it is used to apply a specific intent filter to the subform schema when a form has multiple behaviours defined.
Updated the error log in loadSubForms to include the name of the subform that failed to load so it is clear which one could not be resolved.
Replaced the explicit cast in Promise.allSettled with a type predicate in the filter so TypeScript infers the correct type without needing a cast.
Fixed the error message in page.renderer.component.tsx to guard against showing the word "undefined" when page.subform.name is not set, and updated the message to say "Contact your system administrator" since this will mostly be seen by end users rather than admins or developers.

All test cases are running

Please let me know if there is anything else to address. Thank you!

vivektarun · 2026-03-21T07:48:06Z

@ibacher Would appreciate any feedback whenever you get time. Thank you!

pirupius assigned pirupius, samuelmale, denniskigen and ibacher and unassigned denniskigen, pirupius, samuelmale and ibacher Mar 15, 2026

pirupius requested review from denniskigen, ibacher, pirupius and samuelmale March 16, 2026 06:35

ibacher requested changes Mar 16, 2026

View reviewed changes

address review comments from @ibacher

db46c56

- remove unhelpful inline comments - update formSessionIntent JSDoc - include subform name in error log - use type predicate instead of cast - fix undefined in error message - update error message for end users

vivektarun requested a review from ibacher March 16, 2026 19:47

		// Guard: skip subform pages that have no sections
		// (subform failed to load or is still a reference placeholder)

		// Guard: subform pages have no sections — return empty array
		// so the rest of the component renders safely

		// If this page is a subform page but the subform failed to load,
		// show a helpful inline error instead of crashing.

Uh oh!

Conversation

vivektarun commented Mar 15, 2026

Summary

Related Issue

Root Cause

Changes

Before

After

Screenshots

Tests Passing

How to Test

Checklist

Uh oh!

samuelmale commented Mar 16, 2026

Uh oh!

vivektarun commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ibacher left a comment

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vivektarun commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

All test cases are running

Uh oh!

vivektarun commented Mar 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vivektarun commented Mar 16, 2026 •

edited

Loading

vivektarun commented Mar 16, 2026 •

edited

Loading