Fix Sitecore Content SDK Component Map Errors in Next.js

If you are building a Next.js application using SitecoreAI (formerly Sitecore XM Cloud ) and the Sitecore Content SDK or Sitecore JSS SDK, you may run into this frustrating runtime error:

Placeholder contains unknown component

This issue is more common than it looks and is usually caused by a simple but critical detail: a case-sensitive mismatch between the componentName defined in Sitecore and the key used in your .sitecore/component-map.ts.

In this guide, you will learn why this happens, how Sitecore resolves components, and how to fix it correctly using recommended patterns.

Sitecore dynamically resolves components during rendering using the componentName stored in the Sitecore Rendering definition (/sitecore/layout/Renderings/Project)

Your Next.js application must register components using exactly the same name in the component map.

Because JavaScript Maps are case-sensitive, even a minor difference in casing will break the mapping.

Example Error

Placeholder headless-main contains unknown component herocard

This tells you that Sitecore is sending herocard, but your app does not recognize it due to a mismatch.

The Sitecore Content SDK generates a component map using namespace imports. A typical example looks like this:

import * as PageHeader from 'src/components/page-header/PageHeader';
import * as pageheaderprops from 'src/components/page-header/page-header.props';

export const componentMap = new Map([
  ['PageHeader', { ...PageHeader }],
  ['page-header', { ...pageheaderprops }],
]);

Key Observations

• Namespace imports (import * as X) are required

• Components and props are registered separately.

• The spread operator is used to expose exports.

• Keys must exactly match the componentName from Sitecore.

When creating Sitecore Rendering Items manually or via automated deployment scripts, developers often default to naming items in lowercase. This results in layout payloads like this:

{
  "componentName": "herocard"
}

Incorrect Component Map

['HeroCard', { ...herocard }]  // ❌ mismatch

What Happens at Runtime

• Sitecore sends: herocard

• Component map expects: HeroCard

• Result: Component not found ➡ error

Step 1: Verify the Component Name

Check the actual componentName value using:

• Sitecore rendering item

• Network response in browser dev tools

As a best practice, use PascalCase (e.g., HeroCard) when defining components.

Step 2: Align Component Structure

Ensure your component files follow a consistent naming pattern:

HeroCard/
  HeroCard.tsx
  herocard-props.ts

Step 3: Component Map File (component-map.ts)

Step 4: Restart Dev Server

After making updates, restart your app:

npm run dev

Use consistent naming to avoid mapping issues.

Recommended

HeroCard/
  HeroCard.tsx
  herocard-props.ts

Props Naming Rules

✅ Use: componentname-props.ts ❌ Avoid: component.props.ts

export const Default = (props) => {
  return <div>Component</div>
}

Keep this quick checklist handy when spinning up new components in SitecoreAI and Next.js:

• $$$$

  Ensure the ComponentName field in Sitecore matches your frontend structure and defaults to PascalCase (e.g., HeroCard).

• $$$$

  Keep the component property filename strictly lowercase.

• $$$$

  Name your core component files using PascalCase.

• $$$$

  Do not edit auto-generated component map files

• $$$$

  Restart your local development server whenever you introduce a new component or change file names.

• $$$$

  Double-check the component map output

The unknown component error in Sitecore Content SDK is usually nothing more than a simple case mismatch. Once your component map keys align perfectly with the names coming from Sitecore, the issue disappears instantly.