# Troubleshooting

What to check when the ::: lines show on the page, tabs don't switch, or a choice isn't remembered.

Source: https://rehype-code-group.pages.dev/docs/guides/troubleshooting/

## I see `:::` lines on the page [#i-see--lines-on-the-page]

The plugin leaves a group as plain Markdown when it can't read it. Work through these in order.

1. **Is the plugin running?** It is a rehype plugin, so it must be registered with your rehype or MDX plugins, not with the remark ones.
2. **Is it running at the right point?** It looks for paragraphs and HTML elements. If another plugin turns code blocks into MDX components first, the group seems to have no panels, and you'll get `Code group has 2 labels but 0 panels.` Fumadocs' Shiki plugin is one example. Register rehype-code-group **before** such plugins. Highlighters that produce ordinary HTML elements can run in either order.
3. **Do the labels and panels match?** In compact groups, every block between the markers is a panel. A stray paragraph adds one. Look for the `panel-count` message from the [diagnostics](/docs/reference/options#diagnostics).
4. **Is each marker its own paragraph?** Leave blank lines around `::: code-group …`, `:::`, and in rich groups `:::: code-group`, `::: code-tab …` and `::::`.
5. **Using `[label]` on fences?** The [remark companion](/docs/syntax/fence-labels) must be installed, run before `remark-rehype`, and every fence in the group needs a label. Otherwise the group is left as it is, without a message.
6. **Is it a rich group?** Malformed rich groups don't report anything. Check that each `code-tab` has a `label`, that only blank lines sit between tabs, and that the group ends with `::::`.
7. **Is there a `]` in a label?** Labels in `labels=[…]` can't contain `]`.

Set `diagnostics: "error"` in CI so the problems that can be detected fail the build instead of shipping.

## The tabs are there, but clicking does nothing [#the-tabs-are-there-but-clicking-does-nothing]

The markup is right but the client isn't running.

- With `assets: "none"`, check that your app imports `rehype-code-group/client`, and that the import runs in the browser. In Next.js, that means a client component (`"use client"`).
- With inline assets in a React app, the script is rendered by React and won't run on client-side navigation. Switch to `assets: "none"`. See [Asset delivery](/docs/guides/asset-delivery#your-own-bundle).
- With external assets, check the browser's network panel for the `scriptSrc` URL, and the console for CSP errors.
- Inside a shadow root, call [`initCodeGroups(shadowRoot)`](/docs/guides/browser-client#shadow-dom).

## Every panel is visible at once [#every-panel-is-visible-at-once]

That is the state before the client runs. Groups hide inactive panels only after the client adds `data-rcg-enhanced`. If it stays this way, see the previous section. If the client runs but panels are still visible, check that the stylesheet is loaded, or that your own CSS hides `.rcg-block` inside `[data-rcg-enhanced]`.

## The choice isn't remembered [#the-choice-isnt-remembered]

- `persist` needs a `sync` key. `persist="local"` alone does nothing.
- Only `local` and `url` are valid values.
- Values are matched by tab `value`. If the value changes, for example because it defaults to a label you've reworded, old saved choices no longer match. Set explicit `value`s.
- Some private browsing modes block local storage. The client carries on without saving.

## Groups don't sync [#groups-dont-sync]

- Only [rich groups](/docs/syntax/rich-groups) can have a `sync` key. Groups generated by the package-manager plugin are compact.
- Both groups need the same key, and tabs that should match need the same `value`.

## My styles or colors don't apply [#my-styles-or-colors-dont-apply]

From the release after 2.0.0, any rule you write beats the bundled look, and the `--rcg-*` properties work on the group or any ancestor. See [Overriding the bundled styles](/docs/guides/styling#overriding-the-bundled-styles).

On 2.0.0 and earlier with the default inline assets, the plugin's `<style>` comes after your stylesheet and wins ties. Use a more specific selector, such as `body .rehype-code-group`, and set the properties on the group rather than `:root`.

## Dark mode colors are wrong [#dark-mode-colors-are-wrong]

The default colors follow the page's `color-scheme`. If your theme switch only toggles a class, [set the custom properties](/docs/guides/styling#dark-mode) under that class.

## Duplicate IDs [#duplicate-ids]

IDs are numbered per transformed file, starting at `rcg-0`. If you combine several separately rendered fragments on one page, give each a different [`idPrefix`](/docs/reference/options#idprefix). Otherwise two tabs can share an ID, and `aria-controls` points at the wrong panel.

## MDX errors near a group [#mdx-errors-near-a-group]

In MDX, `{` starts a JavaScript expression and `<` starts a JSX tag, even inside a label. Escape them, for example `\{`, or move the text into a code fence.