facebook/react · error

314

314

Error message

Pinged unknown suspense boundary type. This is probably a bug in React.

What it means

When a suspended boundary is pinged (its wakeable resolved and a retry is scheduled), React looks up the retry bookkeeping by boundary fiber tag: SuspenseListComponent uses stateNode as retry cache, OffscreenComponent uses _retryCache, SuspenseComponent uses suspenseState.retryLane. Any other tag hits the default branch and throws (error code 314) — the boundary was pinged but is not a known suspense boundary type, an internal invariant.

Source

Thrown at packages/react-reconciler/src/ReactFiberWorkLoop.js:5186

    case ActivityComponent:
    case SuspenseComponent:
      retryCache = boundaryFiber.stateNode;
      const suspenseState: null | SuspenseState | ActivityState =
        boundaryFiber.memoizedState;
      if (suspenseState !== null) {
        retryLane = suspenseState.retryLane;
      }
      break;
    case SuspenseListComponent:
      retryCache = boundaryFiber.stateNode;
      break;
    case OffscreenComponent: {
      const instance: OffscreenInstance = boundaryFiber.stateNode;
      retryCache = instance._retryCache;
      break;
    }
    default:
      throw new Error(
        'Pinged unknown suspense boundary type. ' +
          'This is probably a bug in React.',
      );
  }

  if (retryCache !== null) {
    // The wakeable resolved, so we no longer need to memoize, because it will
    // never be thrown again.
    retryCache.delete(wakeable);
  }

  retryTimedOutBoundary(boundaryFiber, retryLane);
}

function throwForcedInfiniteRenderLoopError(
  root: FiberRoot | null,
  renderLanes: Lanes,
): empty {

View on GitHub (pinned to eafeac097b)

Solutions

1. Upgrade to the latest release and check the issue tracker — retry-path invariants have had fixed regressions
2. Simplify the Suspense/Activity nesting around the failing boundary to isolate the trigger
3. File a React issue with the boundary structure and a minimal repro

When it happens

Trigger: A wakeable retry (ping) reaching a boundary fiber whose tag is none of SuspenseComponent, SuspenseListComponent, or OffscreenComponent — e.g. a promise stored on a non-suspense fiber being resolved, or corrupted boundary bookkeeping.

Common situations: Edge cases mixing Suspense, Activity, and error boundaries in canary builds; third-party code resolving thenables that React tracked against an unexpected fiber; historical reconciler regressions in the retry path.

Related errors

• 435
• 462
• react-cache: read and preload may only be called from within
• The should not be any remaining suspense node children if th
• There should always be an Offscreen Fiber child in a hydrate

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/a51c6abf04137814. Report an issue: GitHub.