Troubleshooting
Diagnose missing panels, products, measurement, authentication, and styles.
Start with the loaded bundle version, actual API request, and selected results ownership mode. The browser Network panel distinguishes a setup error, a successful empty response, and an unavailable service section.
Prerequisites
- Read Quick start and Configuration.
- Inspect a test member session without exposing its bearer token.
Common symptoms
| Symptom | Check | Fix |
|---|---|---|
AugeoSearchSdk is missing | Script load status and Content Security Policy | Load the browser IIFE before mounting; permit the selected CDN |
| Nothing mounts | Existing target element | Pass an HTMLElement, not a selector or missing node |
| Field appears but panel stays closed | onOpenChange callback | Apply search.update({ open }) for every visibility request |
| No products after submission | Presence of onSearchSubmit | Render results in the host route or omit that callback for panel mode |
| Product click does nothing | onResultSelect | Provide product navigation or selection behavior |
| Ask AI closes but no chat opens | onAskAi | Connect the callback to an assistant with its seed text |
| Missing catalog request | Token, open state, and results mode | Supply a valid member bearer and submit in panel mode |
| Empty products with HTTP 200 | Products list and unavailable flags | Distinguish no matching products from a section marked unavailable |
| Auth errors | Token accessor and response code | Recover the member session, then retry or reopen |
| Requests target another environment | Explicit apiBaseUrl and bundle defaults | Align the bundle and actual API override with your deployment |
| Failed recent removal | Opaque ID and dismissal response | Retry the recents recovery control; verify persistence against the live service |
| No Remove control | Recent response lacks an ID | Use a handler that provides opaque recent IDs |
| Completion callback does not run | Host mode or canceled/failed request | Use panel mode and observe a current successful catalog response |
No search.submitted on the root bus | Blank or fully redacted term, or an older bundle | Use a current bundle and a nonblank term that survives sanitization. No host completion wiring is required |
| Submission is on the bus but not at the destination | Consent, mapping, allow list, or teardown | Admit the submitted type in the shared analytics configuration and keep the runtime alive through delivery |
No search.performed after products show | presented was not called, or the keyword redacted to null | Call presented from the committed view. A fully redacted term emits nothing |
search.performed fires before results render | Report ran on fetch or router completion | Move the report to the committed products or empty state. search.submitted intentionally fires before results |
| Keyword is the typed prefix | Selection used the field value | Execute and measure the selected suggestion keyword |
| Count equals total matches | resultCount used the match total | Pass the displayed page item length |
| Schema rejects keyword length | A host-built occurrence exceeded 200 characters | Use the SDK event. Do not build the occurrence yourself |
TypeError from presented | Page or count is missing, fractional, or not a safe integer | Correct the facts and call presented again on that handle |
| Empty state emitted success | Count was positive, or the host sent outcome | Pass 0 for an empty page. Do not send outcome |
| Failed search emitted empty | A failure was reported with count 0 | Show the error state and emit nothing. Cancel only a terminal failure |
| Repeat query emitted nothing | The cancelled handle was reused | Submit again so the SDK creates a new execution |
| Stale coffee replaced tea | The old commit was not guarded by execution id | Ignore delayed work for a superseded id |
| Panel close dropped host measurement | The host cancelled on onOpenChange(false) | Keep the shell coordinator alive across panel closure |
| Route leave cancelled the new search | Cleanup read the current id | Cancel only the id captured when that route started |
| Full page load lost the handle | Navigation unloaded the SDK | Keep the shell mounted, or implement a transfer before production |
| Results show but analytics is silent | Mapping or allow omits the performed type | Add that type to mapping and allow. Keep the root listener only |
| Second event on rerender | A rerender was treated as a new search | Duplicate commits are ignored. Do not submit again on rerender |
Script, API, and browser policy
Inspect window.AugeoSearchSdk.version to identify the loaded build.
The global .apiBaseUrl reports the bundle default; inspect requests when the instance overrides that origin.
Permit the CDN in script-src, the selected API in connect-src, and product image origins in img-src.
Ensure the API allows your host origin and Authorization header.
Do not disable browser policy checks to hide an integration failure.
Styles and sizing
The bundle installs its design-system styles and CSS reset inside Shadow DOM. A global host reset does not replace the widget's internal reset. A separate design-system package download is not required for a script embed.
Confirm the release URL and computed styles when buttons, fields, or product rows appear unstyled.
Remove obsolete SDK copies before testing a newly released bundle.
Give the host mount enough width and verify both sides of the 767-pixel breakpoint.
Use branding.theme for supported theme overrides rather than depending on internal element classes.
Recover and change options
Section failure controls retry that section's request. Authentication recovery still requires your host to supply a valid credential. Changing a token does not trigger an automatic retry of the currently failed section.
update({ onSearchSubmit: undefined }) keeps the existing callback.
To return to panel results, destroy the instance and recreate it without onSearchSubmit.
The same rule applies when restoring automatic presentation after an explicit override.
Measurement lifetime
Submission counts are owned by the SDK and do not need a host completion handle. Use the separate performed event when you need confirmed result facts. The lifetime rules below apply to that result measurement.
A throwing analytics adapter must not replace the rendered results. That failure also must not make the execution eligible again. If the products are correct and no event arrived, record a telemetry failure separately. Closing the panel is not abandonment of a host search. Leaving the results route is. An old route must cancel only the id it captured. Full document navigation cannot keep an in-memory handle. Do not treat that flow as accepted until a transfer exists. Compare the symptom with Concrete outcomes.
Gather useful evidence
Record the bundle version, configured API origin, viewport, results mode, and callback name. Include HTTP status and sanitized response shape when a request fails. Label the run live or controlled. Include execution id, displayed count, event count, and schema result. Live means the deployed host and published bundle. Controlled means a fixture, local bundle, or injected catalog. Exclude Authorization headers, member tokens, typed queries, and recent text from shared diagnostics. The sanitized keyword may be recorded as the analytics field.
Related links
- Options and recovery: Configuration
- Ownership and routing: Host integration
- Behavior by interaction: Functionality
- Reproduce with fixtures or live data: Validation