A Content-SDK Upgrade Gotcha

This came up while upgrading a Content SDK project from the pre-release version to the release version. After working through various issues related to the change from React 18 to 19, I thought I had things stable. However, I did my testing with XM Cloud Experience Edge endpoints and not a local docker CM instance. When another developer on the project started using that workflow, he reported getting this error:

Runtime error: GraphQL client misconfigured. Configure one of the following in sitecore.config or your .env file.

Context ID was properly set in configuration, so we couldn't figure out the cause of this issue. I did figure out I was able to get past it if I commented out the 'Redirect' and 'Personalization' handlers in src/middleware.ts.

I gave Christian Hahn on the CSDK team a heads up I was running into this, and he let me know this was addressed with 1.0.1. But, to fix this, it's not sufficient to upgrade your dependencies in project.json, you also have to download a fresh instance of the 1.0.1 starter kit (with "npx create-content-sdk-app@1.0.1 nextjs"), and replace the src/middleware.ts (assuming you haven't modified it) from the 1.0.1 version. You can see the changes to src/middleware.ts here: https://github.com/Sitecore/xmcloud-starter-js/pull/80/files#diff-9669aba000e04fba3a090bd78b705d7b2a7d90e034bdbde5703667524c89b92

The key change is here:

export function middleware(req: NextRequest, ev: NextFetchEvent) {
  // If no Edge server contextId, skip Edge middlewares entirely.
  // (SSR/API can still use Local creds; no crash in Edge runtime.)
  if (!scConfig.api?.edge?.contextId) {
    return NextResponse.next();
  }
  // Instantiate AFTER the guard so constructors don’t run in local-only mode
  const multisite = new MultisiteMiddleware({

As of this writing, there's no Upgrade Guide documentation for 1.0.1, so this step is not called out on the main upgrade guidance:

However, if you follow the steps for 1.0.0, but download the 1.0.1 starter kit (with npx create-content-sdk-app@1.0.1 nextjs), and replace your middleware.ts file with the one from the starter kit, you should be fine. (A similar step occurs in 0.1.0 to 0.2.0 instructions. See text following "If you have not customized the src/middleware.ts file, replace it with the version in your template app" here.)

From my conversation with Christian, I believe 1.0.1 instructions should be available shortly. I'll update this post with a link as soon as that happens.

Much thanks (and vielen dank) to Christian for the real time help with this issue. 🙏