# Troubleshooting

> Symptoms of a widget built from the canonical template, their cause and the fix.

---

## The widget shows "Missing configuration variables"

**Symptom:** instead of the page, the widget shows an alert titled "Missing configuration variables" with a list of variable names.

**Cause:** a variable declared with `requireVariable` in `src/config/widgetConfig.ts` arrived empty or with its Liquid tag unresolved (`{{vars.…}}`). `App` calls `getMissingVariables()` before rendering the page.

**Fix:**
- On a Modyo site: define the listed variables in the site variables.
- To work with mock data: set `vars.use-mocks` to `"true"`; then no variable is required.
- `npm run preview` serves the built `dist/`, where nobody resolves Liquid tags, so it always shows this alert. Use `npm run dev` (it reads `src/config/liquid.json`) or the Modyo CLI preview.

Details: `modyo://docs/widgets/patterns-liquid-environment`.

---

## The widget does not mount

**Symptom:** nothing renders. In development the console shows a warning that no container was found for the widget.

**Cause:** `src/app/main.tsx` mounts on every element with `data-widget="<WIDGET_NAME>"` that is not yet mounted and, if there is none, on the element with `id="<WIDGET_NAME>"`. No element matches.

**Fix:** the container's `data-widget` (or `id`) must equal the `WIDGET_NAME` constant of `src/app/main.tsx`. When renaming the widget, change both. Each container with that `data-widget` gets its own instance.

---

## Dynamic UI styles are missing

**Symptom:** components render without Dynamic UI styles, or with Dynamic's default colors instead of the site's brand.

**Cause:** the widget does not bundle Dynamic UI's CSS, the theme or the fonts: the Modyo site loads them once for the page. `src/app/main.tsx` imports only `@/styles/base.scss`.

**Fix:**
- On a site: check that the site's layout loads Dynamic UI's CSS and its theme.
- In `npm run dev`: `index.html` links Dynamic UI's CSS from the CDN with an absolute URL. To see the site's brand locally, add a `<link>` to the site's theme stylesheet **after** Dynamic's, also with an absolute URL.
- Do not import Dynamic's CSS from `src/`: the validator reports it as an error (*No Dynamic CSS Import*).

---

## A modal or offcanvas does not open

**Symptom:** calling `openPortal('<name>', …)` throws an error.

**Cause:** the portal is not registered in `availablePortals` of the `DContextProvider` in `src/app/main.tsx`. The template starts with `availablePortals={{}}`.

**Fix:** register the component under the name the widget opens:

```tsx
import { EntityCreateModal, type EntityPortals } from '@/features/entities';

<DContextProvider<EntityPortals> availablePortals={{ 'entity-create': EntityCreateModal }}>
```

The validator does not catch this case: it only checks that the text `availablePortals` appears in `src/app/main.tsx`.

---

## "No QueryClient set, use QueryClientProvider to set one"

**Cause:** a TanStack Query hook runs outside `QueryProvider`. `src/app/App.tsx` wraps the page with `QueryProvider`, but portals render next to the `App` tree, outside it.

**Fix:** a modal registered as a portal does not call query hooks. The component that opens it, inside the provider, passes the action in the payload:

```tsx
onClick={() => openPortal('entity-create', { onCreate: createEntity })}
```

Details: `modyo://docs/widgets/patterns-tanstack-query`.

---

## An icon does not appear

**Symptom:** a `DIcon` (or an `icon`, `iconStart`, `iconEnd` prop) renders nothing. There is no error.

**Cause:** the name is not a Lucide icon in PascalCase, or, in a build, it is not in the icon subset. The `lucideSubset` plugin (`vite.config.ts`) only includes names that appear as string literals in `src/`, the icons Dynamic UI uses internally, and the names listed in its `include` option. It only acts in `build`: `npm run dev` sees every icon.

**Fix:**
1. Use a valid Lucide name in PascalCase (`ArrowLeft`, not `arrow-left`).
2. After a build, check `node_modules/.vite/icons-manifest.json`: the name must be in `included`.
3. For a name that never appears as a literal in `src/` (for example, one that comes from an API), add it to `include` in `vite.config.ts`, or declare the possible names in a constant in `src/`.

---

## `dist/` has extra files

**Symptom:** `tests/boundaries/distContents.test.ts` fails, or `widgets-validate` warns *Dist Contents*.

**Cause:** `npm run build` must leave exactly `main.js`, `main.css` and `index.html`. Usual causes: a file in `public/` (Vite copies it to `dist/`), or an image imported in code that Vite emits as a separate file.

**Fix:** serve images from the site or a CDN and reference them by URL. A small SVG can be inlined as a component with `import Logo from './logo.svg?react'`.

---

## Text with `{{ }}` breaks on the site

**Symptom:** a text works locally but appears empty or altered on the Modyo site.

**Cause:** Modyo processes the widget as a Liquid template, so any `{{ }}` or `{% %}` in the bundle is interpreted by the site.

**Fix:** avoid those sequences in texts and translations. Translations interpolate with single braces (`{lang}`). Read site variables through `src/config/widgetConfig.ts`.

---

## `widgets-validate` errors

| Error | Cause | Fix |
|-------|-------|-----|
| `Widget Manifest` / `Profile Selection` | `widget.manifest.json` is invalid or names an unsupported template; no rule ran | Fix the manifest's `template`, or remove the file for a type-based widget |
| `Widget Manifest` / `Missing Manifest` | A domain-structure widget without `widget.manifest.json` | Add the manifest; with `projectFiles`, include it among the files |
| `Stack Alignment` / `stack-alignment` | The major.minor of `@dynamic-framework/ui-react` in `package.json` differs from the Dynamic UI version this MCP pins | Re-create the project with the `widgets-init-project` Prompt, or pass `allowLegacyStack: true` if the divergence is intended |

`stack-alignment` sets `passing: false` without changing the score. Every rule and message: `modyo://docs/widgets/reference-validator-rules` and `modyo://docs/widgets/_meta-validator-quirks`.

---

## See also

- `modyo://docs/widgets/reference-architecture`
- `modyo://docs/widgets/reference-validator-rules`
