2.x
  1. Atoms in Content SDK apps (Early Access)

Troubleshoot atoms

When an atom or a component built from atoms doesn't render as expected, check the catalog, registry, provider configuration, and component layout. For initial setup, see Get started with atoms.

Important

The features described in this topic are available only to customers enrolled in Early Access and are intended for testing in non-production environments.

Design Studio doesn't receive the catalog

Preview requires a catalog on atomsConfig.

  1. Define the catalog with defineAtomsCatalog and export it as catalog from src/atoms/index.ts or src/atoms/index.tsx.
  2. In the provider configuration, pass the catalog as atomsConfig.catalog and the registry as atomsConfig.registry.
  3. Pass the whole return value of defineAtomsRegistry as registry.

During low-code preview, the app sends the catalog to Design Studio. It also sends the catalog when previewing a code component, so generation can use the app's atoms. See Atoms in Content SDK apps.

The atoms capability or catalog metadata is missing

The SDK generates application capabilities in .sitecore/metadata.json. The atoms catalog appears capabilities.designLibrary.atoms.metadata.catalog. If the capability or catalog is missing:

  1. Check that the app retains its SDK Design Studio integration.

  2. Check that SitecoreProvider receives atomsConfig.

  3. Check that generateMetadata receives the catalog through appInputs:

    generateMetadata({ 
    appInputs: { 
        [ATOMS_CATALOG_METADATA_KEY]: catalog, 
    }, 
    }), 
  4. Regenerate metadata with npm run sitecore-tools:build.

  5. Inspect .sitecore/metadata.json and confirm that the catalog contains the expected atoms.

If the catalog is {}, check whether the catalog was supplied to metadata generation and inspect the build output for serialization errors. A valid starter catalog with no components still serializes with empty components and actions lists.

Unsupported JSON Schema portions can appear as {}. Verify both the catalog entries and their schema details. Passing lock-file validation alone doesn't verify the generated metadata.

For imports and configuration, see Get started with atoms.

An atom is missing from a component layout

A component without a matching renderer doesn't render.

  1. Check that the atom appears under the catalog's components key.
  2. Check that the registry's components key contains a React renderer with the same name.
  3. Check that the layout element's type uses that catalog name.
  4. If the element has a visible condition, check whether that condition permits it to render.

Register atoms through atomsConfig. Use the component map for Sitecore rendering components. See Implement atom renderers and slots.

An action doesn't run or an input doesn't update state

Check the event, handler, and binding separately:

SymptomCorrection
A renderer emits an event, but no action runs.Check that the element's on map binds that event name to an action. Emitting press, for example, doesn't itself select an action.
A catalog action doesn't run.Add a registry handler with the same name as the catalog action.
An action doesn't navigate.Provide navigate on atomsConfig and check that the binding sets onSuccess.navigate to a path. The starters use router.push.
An input using useBoundProp doesn't write to state.Check that the prop has a $bindState or $bindItem binding and that the renderer passes the corresponding bindings entry to the hook. Without a binding, the setter does nothing.
An action-only edit passes catalog validation.This is expected: the lock file checks component definitions, not action definitions. Check the catalog action and registry handler directly.

See Add actions and state bindings to atoms.

A published component is missing or uses the wrong variant

On a published page, the SDK loads a component layout when the Sitecore rendering's parameters include ComponentRef.

  1. Check that ComponentRef contains a reference to the intended layout. The component doesn't render if the reference is empty or the SDK can't load the layout.
  2. If the reference lists multiple paths, separate them with |. The last segment of each path is its variant name.
  3. Check the rendering's fieldNames parameter. The SDK selects the path with that variant name, or the path whose variant is default if there is no match.
  4. Check that SitecoreProvider receives atomsConfig with the catalog and registry.

For the rendering flow, see Atoms in Content SDK apps.

Atoms render without the expected CSS

Class names in component layouts aren't present in the app source, so the production CSS build doesn't include them. The SDK can compile class tokens from each element's className prop when rendering the layout.

SymptomCorrection
Design Studio generates styles for the wrong styling solution.Check the catalog's stylingSolution: use tailwind or inline-css. The default is inline-css. This setting describes the styling solution; CSS compilation is separate.
Published layouts have class names but no compiled CSS.Register a CSS compiler at server startup. For Tailwind, use registerTailwindCssCompiler from @sitecore-content-sdk/nextjs/instrumentation with the app's Tailwind stylesheet.
Layout styles are missing during Design Studio editing in an App Router or Cache Components app.Register the compiler and pass compileCssForDocumentAction from @sitecore-content-sdk/nextjs/server-actions as atomsConfig.compileCssAction. It uses the same compiler as published rendering.
The Tailwind stylesheet isn't the one the app uses.Check the path passed to registerTailwindCssCompiler. The default is src/app/globals.css; relative paths resolve from the app root.
Tailwind compiler configuration is incomplete.Keep @tailwindcss/node in serverExternalPackages in the Next.js configuration.
A Pages Router starter renders atoms without layout class styles.The starter doesn't register a compiler. Atoms still render without compiled CSS for layout class names. See the starter differences in Configure styling for atom-based components.

compileCssForDocumentAction returns an empty string when no compiler is registered or the document has no class names. Without a compiler, atoms still render, but layout classes have no compiled CSS. See Configure styling for atom-based components.

The site-level theme doesn't load

Check the following configuration:

Where to checkWhat to verify
sitecore.config.tsEnsure theming.mode is set to site.
SDK client configurationEnsure the client receives the application's theming configuration.
Layout responseVerify sitecore.context.site.name contains the intended site name.
Client Edge contextEnsure the api.edge.clientContextId is configured (normally through NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID).
Page markupCheck whether the <body> includes sc-ds-theme, and the app renders the stylesheet links returned by SitecoreClient.getHeadLinks.
Network requestEnsure the site-theme stylesheet request succeeds.
Editing configuration endpointEnsure it reports theming.mode as site.

Site-level theming and atom class compilation use separate configuration. Setting the catalog's stylingSolution to tailwind, or registering a Tailwind compiler, doesn't enable the site-level theme. The enableThemes option for Design Studio stylesheets also doesn't control this site-level link.

For setup instructions, see Enable site-level theming.

Theme changes don't appear in the preview

If a theme change doesn't appear in the preview:

  1. Check that the app uses SDK packages containing the live-theme preview integration.
  2. Check that theming.mode is site and SitecoreProvider receives theming={scConfig.theming}.
  3. Check that the page is in editing or preview mode and that the app retains its EditingScripts integration.
  4. If a valid theme update has been sent, inspect <head> for the sitecore-theme-preview style element and its CSS. An empty update removes this element.

The live-theme listener applies received preview CSS. It doesn't create, save, or publish a theme. An atom's compileCssAction setting doesn't configure this listener.

A preview layout update doesn't render

The preview checks incoming layouts before rendering them. If a layout is missing or fails structural validation, the update isn't rendered, and Design Studio receives the validation issues so generation can repair it.

Check the layout structure described in Atoms in Content SDK apps:

  • Provide the layout document and its elements map.
  • Set root to the key of the root element.
  • Use element keys for children and named-slot content. A leaf element uses an empty children array.
  • Keep visible, repeat, on, and watch on the element, next to props.
  • Provide the catalog through atomsConfig.

Catalog validation reports errors

The CLI compares .sitecore/atoms.lock.json with the catalog in src/atoms. Use the error code to identify the correction:

CodeMeaningCorrection
MV-010The CLI couldn't find src/atoms/index.ts or src/atoms/index.tsx.Add the atoms module at one of these paths.
MV-011That module doesn't export catalog.Export the result of defineAtomsCatalog as catalog.
MV-012.sitecore/atoms.lock.json doesn't exist.Run npm run sitecore-tools:atoms:update, including for an empty starter catalog.
MV-013The lock file lists a component that the catalog no longer defines.Check whether removal was intentional. To remove it, delete it from the catalog and registry, then run npm run sitecore-tools:atoms:update.
MV-014The catalog defines a component missing from the lock file.Run npm run sitecore-tools:atoms:update to accept the addition.
IV-008The catalog version differs from the lock file. Checked when either side sets a version.Confirm the intended catalog version and update the lock file in the same change.
IV-009A component version differs from the lock file. Checked when either side sets a version.Confirm the intended component version and update the lock file in the same change.
IV-010A component definition changed and its hash no longer matches.Review the change. After an intentional change, run npm run sitecore-tools:atoms:update.
IE-008Validation failed. The issue list follows this message.Correct the listed issues using their codes.
IE-009Validation failed and atoms.validation.breakOnError is true, so the command stops the process.Correct the preceding issues and rerun validation.

After correcting the issues, validate again:

npm run sitecore-tools:atoms:validate

Run the update command to accept intentional catalog changes. Commit .sitecore/atoms.lock.json and leave its generated hashes unchanged. Catalog and component versions are optional; changing a version doesn't replace the lock-file update.

To keep a component available for existing layouts while allowing Design Studio to omit it from new generations, set legacy: true and update the lock file instead of removing the component.

With atoms.validation.breakOnError set to false, validation logs problems and lets dev and build continue. Set it to true when catalog mismatches should stop the process. See Validate and maintain an atoms catalog.

If you have suggestions for improving this article, let us know!