> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/troubleshooting.md).

# Troubleshooting

Checks for the most common problems, from Shopware results instead of InsightSearch to missing products and empty statistics.

If something does not work as expected, you find the checks here in a sensible order. Look up your symptom in the table and jump to the matching section.

| Symptom                                                     | Section                                                                 |
| ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| The shop shows the Shopware search instead of InsightSearch | [The search shows Shopware results](#the-search-shows-shopware-results) |
| The search finds nothing, everything is empty               | [No results](#no-results)                                               |
| The feed is empty or reports an error                       | [Feed empty or error](#feed-empty-or-error)                             |
| Individual products are missing                             | [Products are missing](#products-are-missing)                           |
| A price in the search is wrong                              | [Prices are wrong](#prices-are-wrong)                                   |
| A change is not visible in the search                       | [Changes are not visible](#changes-are-not-visible)                     |
| Indexing stops, for example at 96 percent                   | [Push is stuck](#push-is-stuck)                                         |
| The statistics show no or too little data                   | [Statistics are empty](#statistics-are-empty)                           |
| Orders are missing in the statistics                        | [Orders are missing](#orders-are-missing)                               |
| The search box looks wrong or is missing                    | [Theme conflicts](#theme-conflicts)                                     |
| It is about the quota of search queries                     | [Quota reached](#quota-reached)                                         |
| A message appears in the admin                              | [Notes in the admin](#notes-in-the-admin)                               |

## Check first

Open the overview in the plugin dashboard and look at the "System status". There you see the connection, the data sources, running processes and open problems. Above it, a banner "Current notices: AI-powered product search" may appear. After that, the plugin log in the shop helps (`var/log`, file `cogi_insightsearch-<date>.log`).

## The search shows Shopware results

The InsightSearch search overlay only appears if "Enable search" is on **and** a data source is assigned for the current sales channel and the current language. If it is missing, the Shopware search stays.

Check in this order:

1. Is the plugin active and "Enable search" on, for the right sales channel? Also check the entry "All sales channels".
2. Is there a **language assignment** for exactly this sales channel and this language (Settings, "Assign languages to individual data sources")? The assignment applies exactly per sales channel and language. Otherwise the system status says: "Data sources exist, but no language and no sales channel are assigned yet." The button "Assign languages" takes you there.
3. Does the system status show the connection as "Connected" and the data source as "In sync"?
4. Does the banner "Current notices" show a disruption?
5. Does something in the browser block the calls of the search? Open the developer tools of the browser (Network) and see whether calls to our search service or to `/cogi/insightsearch/auth/session-token` fail. Typical causes are a firewall, bot protection, a strict content security policy or an ad blocker.
6. Does the log say "Fallback auf Shopware-Suche" (the log text is German)?
7. Clear the cache (`cache:clear`) and rebuild the theme (`theme:compile`), especially if a theme of your own overrides the search box. More on this under [Commands](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/commands.md).

Good to know:

* **Layout "Native"** uses the suggestion window of Shopware with InsightSearch hits. The switch "Deliver Shopware search results page via InsightSearch" (default off) delivers the hits of the normal search results page.
* **Fallback during disruptions:** If our search does not answer in time on the server route, Shopware shows its own search. The time limits are about 3 seconds for the search results page and 5 seconds for the suggestion window. After 3 errors in a row, the requests of this sales channel go directly to Shopware for 60 seconds, then it is tried again.
* **Elasticsearch/OpenSearch:** If the Shopware product search runs on Elasticsearch or OpenSearch, InsightSearch does not take over the search results page. The search overlay is not affected.

## No results

The search opens but finds nothing or shows empty pages.

1. Is there a **language assignment** for this sales channel and this language? A wrong assignment, for example to a data source with another language, looks like "no hits".
2. Open the "Sources" area. What is the status, how many products does the data source contain, when was the last indexing? With 0 products the feed is empty, see [Feed empty or error](#feed-empty-or-error).
3. Did you enter fewer characters than the minimum (default 3)? Then the overlay shows a note how many characters are needed, and not "No products found".
4. Are filters active that leave nothing? Use "Reset".
5. Is the rescue for no hits switched off? It is on by default ("Loosen search at 0 hits", "Correct typos", substitute products). If all options are off, the page stays empty. More under [No results](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/no-results.md).
6. Does the language of the feed match the language of the storefront? If the feed in the sales channel has a different language than the storefront, search terms and data do not fit together.

## Feed empty or error

This applies to pull. All error types with cause and measure are on the page [Reading the product feed fails](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/reading-the-product-feed-fails.md). Short version of the order:

1. Open the feed address in a **private browser window**, without login. You find it in the "Sources" area (button "Open feed in browser") or in the sales channel of type product comparison at the very bottom under "Export URL". Does it load? Is it valid XML with `<item>` entries?
2. Look at the error type and the HTTP status in the wizard or in the "Sources" area.
3. Check maintenance mode, htaccess, firewall and bot protection, and the certificate.
4. Does the product export still exist in Shopware under Marketing, Product comparison, and is it active? With "Generate in the background", does the scheduled task of Shopware that creates the file run? Is the file outdated?
5. Look into the Shopware log (`var/log`) for the product export.
6. Check the dynamic product group of the export. The default filter is only "Active = yes". A group of your own with a filter that is too strict, for example on stock, empties the feed.
7. After fixing: "Try again" or "Re-import product data".

## Products are missing

Check whether the product meets the conditions in Shopware:

* **Active and visible:** Only active products that have a visibility in the storefront sales channel are transferred, at least "search only". Products with the visibility "search only" are found but do not appear on category pages. Invisible products, inactive products and products without assignment to the sales channel are missing.
* **Dynamic product group and filters:** They exclude products in the export or push index if the product does not match.
* **Customer group, currency, language:** The feed is generated with the settings of the product comparison sales channel.
* **Stock:** A product counts as available if the available stock is at least the minimum purchase quantity. Hidden closeout items work through the visibility in Shopware.
* **Variants:** If "Combine variants of the same product into one hit" is on (default on), the overlay and the search results page show variants as one hit. If variants should be found individually, for example with their own images or colours, switch the option off. The filter counts continue to count variants.
* **Push:** If the pre-check finds no product ("No products found"), the run does not start.
* **After changes:** "Re-import product data". With pull you also have to wait for the next export run of Shopware.

In the overview, compare the number of products per data source with the number in Shopware. More on the view under [Products in the dashboard](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/products-in-the-dashboard.md).

## Prices are wrong

1. Prices in the search come from the index. It is calculated for **one** customer group, **one** currency and **one** language. Customers of other groups or with special prices otherwise see the price of the index.
2. With the option "Show live prices from Shopware (Beta)", the real, customer-specific price is loaded for every visible hit. This causes an additional query per search. The option cannot be combined with "Hide prices in the search" or "Show prices with RRP prefix".
3. Check how current the price is: with pull, only the next export run and retrieval shows the new price. With push, the next push shows it or, with live synchronisation switched on, the search after about two minutes. See [Push and live synchronisation](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/push-and-live-sync.md).
4. For tiered prices, the feed uses the lowest price (a "from" price).
5. Compare the price in the feed with the currency and customer group of the product comparison sales channel.
6. Is the strike-through price (RRP) correct? Check the fields for sale price and regular price in the feed.

## Changes are not visible

| What you changed                                                                                      | When it becomes visible                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Price, name, image or stock (pull)                                                                    | After the next export run of Shopware and the next retrieval. Immediately: "Re-import product data" in the "Sources" area. With "Generate in the background", wait for the export run first. |
| Price, name, image or stock (push)                                                                    | With the next daily push, with "Re-import product data" or with live synchronisation after about 2 minutes                                                                                   |
| Data fields, data attributes, types, search weighting, boost value, "Transfer sales and margin class" | Only after "Re-import product data"                                                                                                                                                          |
| Filter settings                                                                                       | It can take up to 5 minutes until changes are active                                                                                                                                         |
| New or changed synonyms                                                                               | After a short time (cache, up to a few minutes). A deleted synonym can have an effect until the next re-import.                                                                              |
| Plugin configuration (storefront options, colours, texts)                                             | Clear the Shopware cache (`cache:clear`), for theme changes `theme:compile`. Also keep the browser cache and a CDN in mind.                                                                  |
| Figures of the tile in the Shopware dashboard                                                         | The cache holds for 10 minutes                                                                                                                                                               |

Hit lists of the search results page are also cached briefly, in the order of about 2 minutes.

## Push is stuck

The process is described in detail under [Push and live synchronisation](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/push-and-live-sync.md). The short version of the checks:

1. Is a worker running that processes the `async` queue?
2. Is the PHP memory limit of the worker process (CLI) sufficient, and does Supervisor or systemd restart it after it ends?
3. Is `scheduled-task:run` running? The monitoring runs every 10 minutes.
4. Does the "Sources" area show the note that stuck packages are requeued?
5. Do you see entries with "\[PushIndexing]" and "\[PushFinalize]" in the log?
6. After 15 minutes without progress, or after one hour if no worker is running at all, the run counts as failed. Then start it with "Restart".
7. If it happens often, the catalogue may be very large. Increase the memory limit of the worker.

## Statistics are empty

1. **Is the worker running?** Cart, order and payment status are background messages. Without a worker they stay in the queue. A task catches up on orders every 6 hours, cart events not.
2. Is "Enable order tracking" on? If it is off, cart, order and payment status are not sent.
3. Does the **paid status** fit your payment methods? For invoice or prepayment without the status "Paid", additionally select "Open" under "Paid transaction states", otherwise revenue is missing.
4. Is there a language assignment? Orders without an assignment to a data source are not reported.
5. Are period and time zone right? You set the time zone in the card "Admin dashboard" under "Time zone for statistics" (for example `Europe/Berlin`). Days begin at midnight in this time zone.
6. Bots and crawlers do not count. A test with curl or a script does not appear.
7. Without cookie consent, events are sent with the derived session reference. They still appear, only the recognition across several visits is missing. More under [Data protection](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/data-protection.md).
8. Behind a CDN without trusted proxies set (`TRUSTED_PROXIES` in Shopware), all visitors have the same IP address. The plugin limits events to 120 per minute per visitor and 3000 per minute per IP. Beyond that, events are discarded.
9. Does the statistics page in the admin not load? You need the permission "View orders" for it. See [Permissions](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/permissions.md).
10. The figures of the tile only appear after the cache of 10 minutes.

More on statistics under [Statistics](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/statistics.md).

## Orders are missing

1. Is the task that catches up on orders running (every 6 hours)? It only catches up on orders of the **last 7 days**. Older ones are not caught up.
2. An order counts as revenue if its payment status matches "Paid transaction states". For purchase on invoice, additionally select "Open", then it counts when ordering. Cancellation and chargeback take it out again.
3. **Revenue via the search** counts per purchased product (or its variant) if this product was clicked in the search or put into the cart from there. Up to 72 hours may lie between the click and the order, in the same browser. Other orders are shop revenue, not search revenue.
4. Orders from a language or sales channel without an assignment of its own count with the data source of the same sales channel. Sales channels without an assignment in shops with several data sources are not counted.
5. Orders from the time before the Commander was installed are backfilled with `cogi-insightsearch:suite-backfill`, see [Commands](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/commands.md).
6. Customers who abandon payment have an order that stays "open" and does not appear as paid.
7. Duplicate messages are not a problem: repetitions of the same order are merged by the order ID.

## Theme conflicts

* **Theme of your own:** It can override templates of the search box, the header or the product cards. Old overrides can hide elements. Check the activation mode of the search: Standard, Inline, Via external trigger (with CSS selector) or Search button. The search button helps with themes in which the search field is not permanently on the page.
* **Colours and stylesheet:** You set your own colours with "Custom search colours" or "Custom stylesheet". With the option "Replace default stylesheet" you replace the default styling. More under [Customize design](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/customize-design.md).
* **Other search plugins** replace the search box as well and can conflict with InsightSearch.
* **Elasticsearch/OpenSearch** for the Shopware product search does not go together with taking over the search results page.
* **After changes to the theme:** `theme:compile` and `cache:clear`.
* **Cookie banners from third parties** must use the cookie mechanism of Shopware, otherwise the entry "Recognition for search and recommendations" may not appear.

## Quota reached

In the dashboard you see "Search queries this month", the current search queries and the projection to the end of the month.

* **Search queries:** When the limit is reached, there are no restrictions or automatic extra costs. In case of excessive overuse, we will contact you to find a solution together.
* **Shopping assistant (beta):** When the quota is used up, the assistant is hidden until the first of the month. The search continues normally. From 80 percent a warning appears.
* **Manual re-import:** If the admin shows a message about a used-up quota for manual synchronisations, try again the next day.

## Notes in the admin

| Note                                                                                                        | Meaning                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Banner "Current notices: AI-powered product search"                                                         | Current disruptions and planned maintenance, with the status "Open", "In progress" or "Under observation" and a date. Visible on all tabs, can be hidden in the card "Admin dashboard". |
| "Open problems" in the overview                                                                             | Problems concerning a data source. With "Mark as resolved" you clear an entry once you have fixed it.                                                                                   |
| "Your search indexes were deleted due to inactivity. Please start a new indexing to reactivate the search." | The connection check did not arrive for a long time. Start a new indexing.                                                                                                              |
| "Data sources exist, but no language and no sales channel are assigned yet."                                | Without an assignment, the search does not appear in the shop. Assign languages.                                                                                                        |
| "Connected" or "Not connected", "Check connection"                                                          | Connection status per data source                                                                                                                                                       |
| "The plugin is not yet connected to InsightSearch" in the tile                                              | The setup is not finished                                                                                                                                                               |
| "Some values could not be loaded just now" or "Key figures could not be loaded just now"                    | Try again with "Reload"                                                                                                                                                                 |

For changing actions (indexing, feeds, synonyms, filters, reset), administrators need the permission "Edit system configuration", for statistics, tile and the evaluation of the assistant the permission "View orders".

## Still stuck?

If the steps do not help, open the support dialog in the plugin dashboard. Describe the symptom, the sales channel and the language and add the error message. More under [Feedback, support and Commander](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/feedback-and-commander.md).

## Further reading

{% content-ref url="/pages/hOjMIyte1UMVRSrHsLCy" %}
[FAQ and common problems](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/faq-and-common-problems.md)
{% endcontent-ref %}

{% content-ref url="/pages/b675qqwsZn7vseBK0dd9" %}
[Reading the product feed fails](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/reading-the-product-feed-fails.md)
{% endcontent-ref %}

{% content-ref url="/pages/kG1p17yKCiPZb4o3gw2S" %}
[Push and live synchronisation](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/push-and-live-sync.md)
{% endcontent-ref %}

{% content-ref url="/pages/mU4m1YpoKatMe6lLhFMB" %}
[Commands](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/commands.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
