Troubleshoot an integration

The ready event never fires

1. Listen for iconfigurator.failed before loading the embed.
2. Check the browser network panel for the embed and visualizer assets.
3. Verify CONFIGURATOR_KEY was replaced with the assigned key.
4. Confirm the page contains one #icf_page mount.
5. Inspect console errors from host scripts that execute before the embed.

A preboot plugin appears as a late plugin

The plugin artifact probably finished after the visualizer started. Load it synchronously before embed.cfm and do not add async. Confirm its top-level work only queues the plugin.

settings:filter does not run

The hook is startup-only. Queue the plugin before the embed. Late registration cannot change startup settings for the current page load.

A UI contribution duplicates itself

Return cleanup from every outlet callback. Repeated card and detail outlets remount when context changes.

return () => {
  button.removeEventListener('click', handleClick)
  button.remove()
}

Styles appear on the host page but not the plugin

If host-page styles do not affect plugin UI, register those styles through api.ui.addStyle().

A price resolver has no effect

• Return synchronously from price:resolve.
• Confirm account settings allow pricing to be shown.
• Call api.commands.refreshPricing() after a plugin-owned price cache changes.
• Inspect pluginErrors for an invalid or asynchronous return.

A plugin cannot change a wheel request

Raw API request construction is not a public plugin surface. wheel-query:filter is reserved but not implemented. Use result filters, destination resolution, or app commands for supported tasks.