---
title: "Troubleshoot atoms"
slug: "troubleshoot-atoms"
abstract: "Resolve missing atoms, action and state-binding issues, component-layout rendering problems, missing CSS, and catalog validation errors."
---
# 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/get-started-with-atoms.html).

> [!important]
> The features described in this topic are available only to customers enrolled in [Early Access](https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=hAFwkRTDyU27fqQR30VqHj_zY3lpy3dGhZKklnheMCxURUpHTkhSSzI4QkhCUFMzSDM2M1ZGRkYwMi4u) 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/atoms-in-content-sdk-apps.html#preview-and-editing).

## 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:

    ```ts
    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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/get-started-with-atoms.html).

## 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/implement-atom-renderers-and-slots.html).

## 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. |

See [Add actions and state bindings to atoms](https://doc.sitecore.com/sai/en/developers/content-sdk/20/add-actions-and-state-bindings-to-atoms.html).

## 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/atoms-in-content-sdk-apps.html#atoms-and-sitecore-renderings).

## 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/configure-styling-for-atom-based-components.html#check-the-starter-configuration). |

<!-- Note for later: The Pages Router editing-time compiler procedure in atoms.md line 352 remains unverified. As in the styling draft, no runnable Pages Router Server Action instructions are provided pending confirmation. -->

`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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/configure-styling-for-atom-based-components.html).

### 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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/configure-styling-for-atom-based-components.html#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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/atoms-in-content-sdk-apps.html#component-layouts):

- 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`.

<!-- Note for later: origin/release/betas/atoms packages/content/src/atoms/design-library-bridge/validate-document.ts and events.ts validate incoming updates, report issues to Design Studio, and reject invalid updates before invoking the callback. This supports structural-validation guidance. The source's broader wording that an invalid layout is "left unrendered" must not imply that an existing valid preview is cleared: the branch rejects the new update without clearing the previous document. The no-elements-object guard is verified; behavior for an empty elements map is delegated to @json-render/core validateSpec and remains pending dependency verification because it is not installed. Do not claim validation against catalog prop schemas or placement constraints. -->

## 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:

```shell
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](https://doc.sitecore.com/sai/en/developers/content-sdk/20/validate-and-maintain-an-atoms-catalog.html).
