FAQs

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.

"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.skip or dispatch.error entries. Items outside the Item set filter are skipped by design.

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, the vector index is stale. Re-index Now rebuilds it.
  • 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 and re-index, because site membership is stored with each chunk.
  • 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.

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 gets an admin URL and is excluded from site-scoped results. Assign it to a site and 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. 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 and has not rebuilt the vector index, 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 ticked) so every item and media chunk records its item sets. 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