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.
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.
- Define the catalog with
defineAtomsCatalogand export it ascatalogfromsrc/atoms/index.tsorsrc/atoms/index.tsx. - In the provider configuration, pass the catalog as
atomsConfig.catalogand the registry asatomsConfig.registry. - Pass the whole return value of
defineAtomsRegistryasregistry.
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:
-
Check that the app retains its SDK Design Studio integration.
-
Check that
SitecoreProviderreceives atomsConfig. -
Check that
generateMetadatareceives the catalog through appInputs: -
Regenerate metadata with
npm run sitecore-tools:build. -
Inspect
.sitecore/metadata.jsonand 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.
- Check that the atom appears under the catalog's
componentskey. - Check that the registry's
componentskey contains a React renderer with the same name. - Check that the layout element's
typeuses that catalog name. - If the element has a
visiblecondition, 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:
| Symptom | Correction |
|---|---|
| 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. |
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.
- Check that
ComponentRefcontains a reference to the intended layout. The component doesn't render if the reference is empty or the SDK can't load the layout. - If the reference lists multiple paths, separate them with
|. The last segment of each path is its variant name. - Check the rendering's
fieldNamesparameter. The SDK selects the path with that variant name, or the path whose variant isdefaultif there is no match. - Check that
SitecoreProviderreceivesatomsConfigwith 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.
| Symptom | Correction |
|---|---|
| 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 check | What to verify |
|---|---|
sitecore.config.ts | Ensure theming.mode is set to site. |
| SDK client configuration | Ensure the client receives the application's theming configuration. |
| Layout response | Verify sitecore.context.site.name contains the intended site name. |
| Client Edge context | Ensure the api.edge.clientContextId is configured (normally through NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID). |
| Page markup | Check whether the <body> includes sc-ds-theme, and the app renders the stylesheet links returned by SitecoreClient.getHeadLinks. |
| Network request | Ensure the site-theme stylesheet request succeeds. |
| Editing configuration endpoint | Ensure 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:
- Check that the app uses SDK packages containing the live-theme preview integration.
- Check that
theming.modeissiteandSitecoreProviderreceivestheming={scConfig.theming}. - Check that the page is in editing or preview mode and that the app retains its
EditingScriptsintegration. - If a valid theme update has been sent, inspect
<head>for thesitecore-theme-previewstyle 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
elementsmap. - Set
rootto the key of the root element. - Use element keys for
childrenand named-slot content. A leaf element uses an emptychildrenarray. - Keep
visible,repeat,on, andwatchon the element, next toprops. - 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:
| Code | Meaning | Correction |
|---|---|---|
MV-010 | The CLI couldn't find src/atoms/index.ts or src/atoms/index.tsx. | Add the atoms module at one of these paths. |
MV-011 | That 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-013 | The 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-014 | The catalog defines a component missing from the lock file. | Run npm run sitecore-tools:atoms:update to accept the addition. |
IV-008 | The 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-009 | A 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-010 | A component definition changed and its hash no longer matches. | Review the change. After an intentional change, run npm run sitecore-tools:atoms:update. |
IE-008 | Validation failed. The issue list follows this message. | Correct the listed issues using their codes. |
IE-009 | Validation 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:
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.