Start here when something does not work and you need the fastest safe recovery path.

Troubleshooting pages explain symptoms, likely causes, and where to look next. Use package, API, Search, Event, and reference pages for exact exports, props, fields, schemas, and payloads.

React SDK components render unstyled

Likely causes:

• @enadhq/enad-react-sdk/styles.css is not imported
• the stylesheet is imported in a route that does not wrap the rendered component
• the app is rendering a component-set variant without the SDK styles present

Recovery:

1. Import the stylesheet once in the app shell or global CSS entry.
2. Confirm the route that renders SDK components uses that shell.
3. Reload the app and test a basic component before debugging theme state.
4. See First React SDK app and React SDK setup.

Provider context is missing

Symptoms:

• SDK hooks or connected components fail at runtime
• resolver-backed components do not behave consistently
• search or client-aware UI cannot find runtime configuration

Recovery:

1. Wrap the app runtime boundary in EnadProvider.
2. Add provider options only when the app owns the corresponding integration.
3. Keep EnadThemeProvider inside EnadProvider, not beside or above it.
4. For live Search GraphQL flows, confirm the app provides the required client/search configuration at the runtime boundary.

Playground theme hash does not restore

Likely causes:

• the hash copied from the playground is not the same hash used in the app
• EnadThemeProvider is missing or placed outside EnadProvider
• explicit props override decoded hash values
• the SDK stylesheet is missing

Recovery:

1. Confirm EnadProvider wraps EnadThemeProvider.
2. Pass the playground hash to EnadThemeProvider.
3. Remove explicit componentSet or token props if the hash should win. Explicit props override decoded hash values, and SDK defaults come last.
4. Confirm the SDK stylesheet is imported.
5. Compare against the same state in the live playground.
6. See Restore a theme from the playground.

Component set is missing

Check these causes before changing resolver code:

• componentSet is set outside the themed subtree.
• A hash value and an explicit prop set different variants.
• The stylesheet or generated CSS is missing.
• The component is not part of the resolver-backed surface you expected.

Recovery:

1. Confirm the component is rendered beneath EnadThemeProvider.
2. Confirm componentSet is the value you intend to test.
3. Check whether explicit props override the decoded hash state.
4. Confirm the SDK stylesheet is imported.
5. Treat componentSet as structural, not as a color preset.
6. See React SDK theming and EnadThemeProvider.

Search is not loading

Check these causes before changing Search queries:

• Visual search is rendered without live Search GraphQL configuration.
• App, market, store group, or locale context is missing.
• Route state and request state are out of sync.
• Stale requests are overwriting newer results.

Recovery:

1. Decide whether the component should be submit-only or live-data-backed.
2. For submit-only search, handle the query in app route or page state.
3. For live suggestions or results, configure the root EnadProvider with the app-owned shopper client and search settings.
4. Check Search GraphQL query shape against the Search reference and package types; do not infer fields from UI guide prose.
5. Add empty, loading, error, retry, and stale-result states around the UI.
6. See Product listing and search and Search GraphQL latest.

Product page purchase controls fail

Check these causes before changing the commerce integration:

• A presentational component is being treated as cart or checkout authority.
• The page has not resolved a concrete purchasable variant.
• Inventory, price, or fulfillment state is stale.
• Side effects are hidden inside a display component instead of app-owned handlers.

Recovery:

1. Keep VariantSelector as controlled option-selection UI.
2. Resolve the concrete variant before purchase controls run.
3. Keep add-to-cart, checkout, payment, and delivery side effects in the app commerce integration.
4. Use Price for localized numeric money display, not tax or promotion-rule computation.
5. See Product detail page.

API calls fail with auth or shape errors

Likely causes:

• wrong API or environment
• missing or stale auth credentials
• wrong app, market, store, or locale context
• request body was copied from prose instead of reference/OpenAPI truth

Recovery:

1. Identify the API first: Management, Shopper, Auth, Media, or Asset library reads and DAM administration.
2. Check reference or OpenAPI-derived pages before changing request shape.
3. Confirm auth, app context, environment, market/store/locale, and runtime placement.
4. If Search GraphQL is involved, start from Search GraphQL latest.
5. Use Reference for reference surfaces as they land.

Agent files or llms output is confusing

Symptoms:

• an agent cites stale package/API facts from prose
• llms.txt points to guidance but not exact schema truth
• a tool needs structured route data rather than long-form prose

Recovery:

1. Use /llms.txt for the shortest agent index.
2. Use /llms-full.txt when the task spans several Enad areas.
3. Use /ai/manifest.json for structured route and version-track data.
4. Treat agent files as routing guidance. Exact SDK/API facts still come from package docs, OpenAPI, Search schema, or event catalogs.
5. See Agent guides, React SDK agent guide, and API and Search agent guide.

If you still cannot identify the reference

Use this order:

1. Package/component behavior: SDK package reference.
2. API endpoint truth: reference or OpenAPI source.
3. Search GraphQL truth: Search schema or reference.
4. Runtime experiments: live playground.
5. Flow, composition, and recovery guidance: docs authored guides.