Heft + SPFx < 1.22 = Runtime Errors (and the Fix) when running "serve" (heft start)

If you’ve recently converted an SPFx project to use Heft, but your SharePoint Framework version is below 1.22.x, you may hit a pair of opaque runtime errors that don’t clearly point to the real problem.

The Symptoms

You’ll see something like:

Uncaught runtime errors:

ERROR

Unknown promise rejection reason

    at handleError (https://localhost:4321/dist/...)

And sometimes (see below my guess as to when):

Uncaught runtime errors:

ERROR

Old FRE behavior is disabled

    at get._deferLoadingFeatureHostControl (...)

This looks like something fundamentally broken in your web part. In reality, the issue is a tooling/runtime mismatch.

Root Cause

When you migrate an SPFx project to use Heft, you are effectively aligning with the newer SPFx build pipeline.

However:

• Heft-based builds assume SPFx 1.22.x+

• Projects running SPFx 1.21.x or earlier are not fully compatible

• The failure manifests at runtime, not build time

This is why everything may compile successfully, but the web part fails during execution.

To make things more interesting:

If you are using:

import { ???? } from '@pnp/spfx-controls-react';

@pnp/spfx-controls-react

You may encounter additional friction after upgrading, because at the time of writing, some PnP controls have not been fully aligned with SPFx 1.22.x typings.

I am not 100% sure, but I think this caused the second issue (the Old FRE behavior is disabled error)

The Fix

Step 1 — Upgrade to SPFx 1.22.x

Upgrade your project to:

"@microsoft/sp-component-base": "1.21.1",
"@microsoft/sp-core-library": "1.21.1",
"@microsoft/sp-lodash-subset": "1.21.1",
"@microsoft/sp-office-ui-fabric-core": "1.21.1",
"@microsoft/sp-property-pane": "1.21.1",
"@microsoft/sp-webpart-base": "1.21.1",

Version:

1.22.x

Then:

Delete node modules folder, delete the package-lock.json file, and run npm install.

Rebuild and repackage.

This resolves the Heft runtime mismatch.

---

After Upgrading: PnP Controls Typing Issue

Once upgraded, you may see TypeScript errors with PnP React controls — especially around context.

Example:

<FilePicker
  context={this.props.context}
/>

You may get a typing error because the control expects a slightly different context type under 1.22.x.

Temporary Workaround

Cast the context to any:

<FilePicker
  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SPFx 1.22 temporary compatibility workaround for PnP controls
  context={this.props.context as any}
/>

Yes — this will raise a lint warning.
Yes — you are intentionally suppressing it.
Yes — it is acceptable as a temporary compatibility shim until the PnP controls fully align.