FAQs Omeka S module

Troubleshooting

"Turso Not Available" on the settings page

The module could not connect or create its table. The text after the heading gives the reason:

  • "Turso database URL and auth token must be set": one of the two fields is empty. The token field is blank on every page load, but a saved token is kept unless you type a new one.
  • "Turso HTTP 401" or "Turso HTTP 403": the token is invalid or belongs to a different database. Create a new one with turso db tokens create <db>.
  • "Turso cURL error": the server cannot reach *.turso.io over HTTPS. Check outbound firewall rules and DNS.

Both libsql:// and https:// URLs are accepted.

"Index needs rebuilding" on the settings page

Turso answers, but the index cannot be searched or written, so chat, search and indexing are paused (visitors get a "temporarily unavailable" message, and nothing is sent to OpenAI). The text gives the reason:

  • "The vector index in Turso is damaged": the chunks_vec_idx index is defined but its chunks_vec_idx_shadow table, where libSQL keeps the index graph, is missing. Every search and insert then fails with errors such as vector index(search): failed to select start node for search. Versions before 1.5.3 dropped and recreated the index after every indexed resource, and a drop that failed on the Turso side could leave it in this state.
  • "The vector index (chunks_vec_idx) is missing from Turso": the table is there but its index is not, so searches fail.
  • "The index holds N-dimension embeddings but the Embedding dimensions setting is M": see the embedding-size question below.

Fix: click Purge All Index Data on the Diagnostics tab, then Re-index Now with every content type ticked. If the purge reports an error, create a new Turso database (turso db create <name>, then turso db tokens create <name>) and enter its URL and token on the Connection tab: the module creates a fresh table and index on its first connection. Then re-index.

"OpenAI API key is not configured"

No key was found in local.config.php (chatbot.openai_api_key) or in the encrypted setting. Paste the key into OpenAI API key on the Connection tab and save. If you changed chatbot.encryption_key after saving a key, the stored value can no longer be decrypted; save the key again.

Nothing is indexed after saving items

  • Check Auto-index items on save on the Behaviour tab.
  • Check the settings page header says Turso is available. Saves never fail because of the chatbot, but indexing is silently skipped when Turso is unreachable.
  • Check Admin > Jobs for Chatbot\Job\IndexItemJob entries. A job that stays at "starting" means Omeka's background job runner is not working. Verify the PHP CLI path (cli.phpcli_path in local.config.php); the problem is not specific to this module. As a test, set 'chatbot' => ['sync_jobs' => true] in local.config.php to run the jobs inline.
  • Check View Logs for index.embed, index.problem, index.skip or dispatch.error entries, and the settings page for an Index needs rebuilding message. Items outside the Item set filter are skipped by design. With auto-indexing off, an item added to one of the filter's sets is not indexed until you re-index it (Re-index selected on the Items browse page).

The chatbot answers "I don't know" to everything, or search finds nothing

  • Click Run Test Search on the Diagnostics tab. If Chunks indexed is 0, run Re-index Now.
  • If chunks exist but Results returned is 0, run Re-index Now. If the test search reports an index problem, see "Index needs rebuilding" above.
  • If the widget is on a site whose items are not assigned to that site, site filtering removes them. Assign the items to the site in their form or with a batch edit: their chunks are updated at once. Items assigned on the site's Resources page need a re-index, because site membership is stored with each chunk.
  • If Run Test Search shows a Hidden, not public line, those matches belong to resources visitors may not see (private, unpublished, scheduled for later, or restricted by the Access module) and are never used.
  • Only the Top-K closest chunks are shown to the model. Broad questions about a large collection may not retrieve the right evidence; try a more specific question or raise Top-K.

The settings page says "Content visitors cannot see may still be stored in the index"

Versions before 1.5.3 indexed private items and media too, and versions before 1.5.4 indexed items and media the Access module restricts. Chat and search no longer use them, but their chunks stay in Turso until you click Remove Non-Public Chunks on the Diagnostics tab. The job checks every indexed resource against MySQL and deletes the chunks of anything private, unpublished, restricted or deleted; it makes no OpenAI calls. The notice disappears when the job finishes. See Indexing Content.

A private item still shows in answers or search results

It should not: chat and search check visibility before using a passage. Check that the item is really private (and not only missing from a site), and that a page's site, or a media record's item, is private where you expect. The Access module's levels and embargoes are followed while Access is active (see the next question). Other modules that hide public items in their own way are not consulted; make such items private in Omeka, or keep them out with the Item set filter.

Content restricted or embargoed with the Access module

While Access is active, items and media with a level other than free, or under embargo, are left out of answers and search, and Reserved too, although Access opens it to some visitors: the chatbot answers every visitor alike. If restricted content still appears, check the status Access shows in the item's sidebar (the level after inheritance from its item sets), and that Access is active on Admin > Modules.

Content that is free again does not come back on its own when Access changes it without saving the item: a level changed on an item set, a batch edit of access levels, or the daily embargo task that lifts the level when an embargo ends. Save the item, or select the items and use Re-index selected (or Re-index Now). An embargo with an end date on free content needs nothing: the content is indexed in advance and shows up once the date has passed. See Restricted files and embargoes.

Source links point to /admin/ URLs or the wrong site

Links are built from the first site an item belongs to and rewritten to the site being browsed. An item that belongs to no site links to the installation's first site (an admin URL when there is no site at all) and is excluded from site-scoped results. Assign it to a site in its form: its chunks and its media's get the new site at once. Items assigned on a site's Resources page need a re-index.

I changed the embedding model or dimensions and now indexing or search fails

The Turso chunks table is created with a fixed vector size, and until it matches the setting the settings page shows Index needs rebuilding and indexing and chat are paused. After changing Embedding dimensions, click Purge All Index Data on the Diagnostics tab to drop and recreate the table with the new size, then Re-index Now. Changing only the model also needs a full re-index so old and new vectors are not mixed.

Visitors see "Rate limit exceeded"

The chat and search endpoints allow 10 requests per IP address per 60 seconds by default, and the two endpoints share that budget. Visitors behind one shared IP, such as a school or office, share it too. If your site is behind a proxy or CDN that does not send X-Forwarded-For or CF-Connecting-IP, every visitor appears to have the same address. Fix the proxy headers, or raise chatbot_rate_limit_max as described in Configuration.

The floating widget does not appear

  • Enable global chat widget on all public pages must be checked and saved.
  • It only appears on public site pages under /s/, never on admin pages or the top-level index.
  • Your theme's layout must call headLink() and headScript(), as the default theme does; the widget's CSS and script are added through them.

A bulk re-index is slow or costs more than expected

Every chunk is one embeddings API call, and a 3200-character chunk is roughly 800 tokens, so cost scales with the total text. Reduce it with an Item set filter, by ticking fewer content types, or by switching to text-embedding-3-small with 1536 dimensions (purge and re-index afterwards). A running job can be stopped from Admin > Jobs; a stopped run has already cleared the old chunks of the types it reached, so run it again to completion.

Editors get a permission error from Run Test Search

Since version 1.5.0 the diagnostics request is granted to editors, site admins and global admins, the same roles that can open the settings page. If an editor still sees a permission error, the module has not been upgraded: open Admin > Modules and upgrade Chatbot, then reload the settings page.

A block restricted to item sets returns "I don't know" or no results

The restriction matches item set membership stored with each chunk, and chunks written before version 1.5.0 carry none. Run Re-index Now on the Diagnostics tab (with Items and Media ticked) so every item and media chunk records its item sets. Since 1.5.4, adding an item to a set or removing it in its form or a batch edit updates its chunks and its media's at once; before, media kept the old sets until re-indexed. Also check that the items really are in the selected sets, and remember that blog posts and site pages are never returned while a restriction is set. The global Item set filter on the Models & Search tab is separate: it decides which items are indexed at all. See Indexing Content.

Anonymous visitors see "Please log in to use the chat"

The Chatbot block's Allow anonymous users option is unchecked. Edit the page, tick the option on the block and save. Blocks that existed before version 1.5.0 were set to allow anonymous users during the upgrade, so this only happens for blocks where the option was unchecked afterwards.

Does uninstalling delete my data?

Uninstalling drops the module's log and rate-limit tables in MySQL. The Turso chunks table and the module's settings remain. See Installation.

Log in for Support