From ba104a1f1ec1dc3a46482b63ea1e24be72c0da93 Mon Sep 17 00:00:00 2001 From: reeb Date: Sun, 27 Sep 2026 20:24:13 +0300 Subject: [PATCH 1/7] RDoc-4067 added /quill/troubleshooting --- quill/dashboard/manage-an-app/agents-view.mdx | 29 +- .../connecting-your-database.mdx | 8 +- quill/logging.mdx | 2 +- quill/networking-and-dns.mdx | 2 +- .../operator-authentication.mdx | 2 +- quill/troubleshooting.mdx | 1445 +++++++++++++++++ 6 files changed, 1477 insertions(+), 11 deletions(-) create mode 100644 quill/troubleshooting.mdx diff --git a/quill/dashboard/manage-an-app/agents-view.mdx b/quill/dashboard/manage-an-app/agents-view.mdx index 3eeb9c844e..88a5452779 100644 --- a/quill/dashboard/manage-an-app/agents-view.mdx +++ b/quill/dashboard/manage-an-app/agents-view.mdx @@ -177,11 +177,13 @@ You can expand or collapse each configuration section: [Basic settings](#basic-s A description of the data the query returns. * **C. Query** Query tools can only **read** from Quill's internal database, never write into it. - When a `$name` placeholder is included in the query, Quill replaces the placeholder at runtime, each time the query - tool is called, with the value set by an agent parameter of the same name. - When no agent parameter carries the placeholder's name, the value is taken from the parameters the LLM provides - when it requests the query, defined in **D** below. - The query will fail if neither an agent parameter nor the LLM provides a value for the placeholder. + When a `$name` placeholder is included in the query, Quill replaces the placeholder, each time the query tool is + called, with a value from one of two sources: + * An agent parameter of the same name, whose value is set when a conversation starts. + * A parameter of the same name defined in **D** below, whose value the LLM provides when it requests the query. + + Each placeholder must have exactly one of these sources: Quill refuses to save the agent's configuration if a + placeholder has neither, or has both. * **D. Sample parameters object / Parameters JSON schema** Define, either as a **sample object** or as a **JSON schema**, the parameters the LLM provides when it requests this query. @@ -219,6 +221,16 @@ You can expand or collapse each configuration section: [Basic settings](#basic-s Either a sample object or a JSON schema must be defined. If you define both, the schema will be applied. + + + + A parameter that the query uses as a placeholder counts as the placeholder's source only if it is defined as + **required**: + * Quill defines every parameter of a sample object as required. + * In a JSON schema, list the parameter name under the **`required`** field, and describe it under the **`properties`** + field, which tells the LLM the parameter's type and what value to provide for it. + + * **E. Allow model queries** Select whether the LLM is allowed to run this query tool. **True**: the LLM can run the tool whenever needed. @@ -307,6 +319,11 @@ You can expand or collapse each configuration section: [Basic settings](#basic-s * **D. Webhook URL** The address Quill calls when the agent triggers the action. The address must be absolute, and start with `http://` or `https://`. + + + Quill waits 30 seconds at most for the outside system's response, and does not follow redirects, so the address must + be the one that answers the call itself. + * **E. Secret** An optional value Quill sends with every call, for the receiver to check. * **F. Max response size (optional)** @@ -318,7 +335,7 @@ You can expand or collapse each configuration section: [Basic settings](#basic-s Leave the configuration without saving your changes. 8. **Test agent** Chat with the agent to try the configuration currently in the form, unsaved changes included. - The button stays disabled until the agent name, the system prompt, and the connection string are all set. + The button stays disabled until the system prompt and the connection string are both set. 9. **Save changes** Save the modified configuration. A save attempted while any configuration section still requires your attention opens all four sections, and marks diff --git a/quill/getting-started/connecting-your-database.mdx b/quill/getting-started/connecting-your-database.mdx index 0fec3e175e..b986f0ecd2 100644 --- a/quill/getting-started/connecting-your-database.mdx +++ b/quill/getting-started/connecting-your-database.mdx @@ -233,8 +233,12 @@ using a `GRANT` statement. keeps and where the server is writing now. Quill does not check these privileges. -A missing `SELECT` privilege surfaces in the [Verify your schema](#verifying-your-schema) -stage, where Quill reads from the tables you select. +A missing `SELECT` privilege surfaces before Quill verifies the tables: +* MySQL and MariaDB servers show a user only the tables the user holds a privilege on, so a table the database user + holds no privilege on is not listed in the [Verify your schema](#verifying-your-schema) stage. +* A database user who holds no privilege on the source database at all cannot connect to it: clicking **Test connection** + reports that access to the database is denied. + A missing `REPLICATION SLAVE` or `REPLICATION CLIENT` privilege surfaces only after the app is created, when Quill starts following the changes. diff --git a/quill/logging.mdx b/quill/logging.mdx index 4c4a9843c0..7ded54e15c 100644 --- a/quill/logging.mdx +++ b/quill/logging.mdx @@ -1,5 +1,5 @@ --- -title: "Logging" +title: "Quill: Logging" sidebar_label: Logging sidebar_position: 8 description: "Locate Quill's service, application, and audit logs; configure log levels and optional file sinks; and use a custom NLog configuration." diff --git a/quill/networking-and-dns.mdx b/quill/networking-and-dns.mdx index 980f08d1d2..bc87b922c8 100644 --- a/quill/networking-and-dns.mdx +++ b/quill/networking-and-dns.mdx @@ -1,5 +1,5 @@ --- -title: "Networking & DNS" +title: "Quill: Networking & DNS" sidebar_label: "Networking & DNS" description: "The DNS records created for your Quill instance, what they point at, and how to repoint them when your server's IP address changes." sidebar_position: 6 diff --git a/quill/security-and-architecture/operator-authentication.mdx b/quill/security-and-architecture/operator-authentication.mdx index a864edf680..348eed3fff 100644 --- a/quill/security-and-architecture/operator-authentication.mdx +++ b/quill/security-and-architecture/operator-authentication.mdx @@ -188,7 +188,7 @@ and recreate the container. ### Recreate the container In these commands, `` is the name specified after `--name` in your original `docker run` command. -By default, it matches your Quill name. +The sign-up Docker command sets it to `quill-` followed by your Quill name, e.g., `quill-baloo`. `` is the volume name specified before `:/var/lib/quill` in that command. Remove the existing container, then rerun it with the new key and the same data volume: diff --git a/quill/troubleshooting.mdx b/quill/troubleshooting.mdx new file mode 100644 index 0000000000..90fcba38fe --- /dev/null +++ b/quill/troubleshooting.mdx @@ -0,0 +1,1445 @@ +--- +title: "Quill: Troubleshooting" +sidebar_label: Troubleshooting +sidebar_position: 9 +description: "Symptoms that may appear while setting Quill up or running it, each with its likely cause and what to do about it." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Quill: Troubleshooting + + +* The symptoms below may be met while setting Quill up or running it, each listed with its likely cause and what to do about it. + +* The fixes for most symptoms are explained in the articles that document the affected features. + Such a symptom's entry states the fix in brief, and links to the article section that explains the fix in full. + +* Some causes are named only in Quill's logs, e.g., an LLM provider that no longer accepts the API key set in an + AI connection string. + + + Find the location and content of each Quill log in [Logging](logging.mdx#log-locations). + + +* The symptoms of each channel type are listed in the channel's own article, as described in [Channels](#channels). + +* If a problem remains after you followed its entry, contact RavenDB's support, as described in + [Contacting support](#contacting-support). + +* In this article: + * [Starting Quill](#starting-quill) + * [Signing in to the management dashboard](#signing-in-to-the-management-dashboard) + * [Connecting the source database](#connecting-the-source-database) + * [Mapping the source tables](#mapping-the-source-tables) + * [AI connection strings](#ai-connection-strings) + * [Agents](#agents) + * [Mirroring](#mirroring) + * [Channels](#channels) + * [Network and DNS](#network-and-dns) + * [Updates and expiry](#updates-and-expiry) + * [Contacting support](#contacting-support) + + + + + +Quill reports its progress in the terminal you ran the Docker command in, until `Status: READY` indicates that your +deployment can be accessed, as described in [Starting Quill: Watching Quill come up](getting-started/starting-quill.mdx#watching-quill-come-up). +The symptoms below may appear while Quill starts, or keep Quill from starting. +In the commands below, `quill-` is the name the sign-up Docker command gives the container, where `` is +your deployment name. If the container was started under another name, use that name instead. + + + +##### Port 443 is already in use + +`docker run` fails with an error that port 443 is already allocated, already in use, or not available. + + + +**Likely cause:** another container or program on Quill's machine uses port 443 (e.g., an earlier Quill container, or a web server). + + + +**What to do:** stop the program that uses port 443, remove the container if Docker created one, using +`docker rm -f quill-` with your container's name instead of `quill-`, and run the Docker command you copied at sign-up again. + + + + + +##### The license key is not set + +The terminal prints `ERROR: QUILL_LICENSE_KEY is not set, so the appliance cannot activate.` + + + +**Likely cause:** the Docker command was executed without its `-e QUILL_LICENSE_KEY=...` line, or with an empty value. + + + +**What to do:** remove the container using `docker rm -f quill-` with your container's name instead of `quill-`, +and run the Docker command you copied at sign-up again, unchanged. + + + + + +##### The license key is not recognized + +The terminal prints `Status: FAILED` with `Reason: activation failed: the license key was not recognized`. + + + +**Cause:** the RavenDB service at `api.ravendb.net`, from which Quill fetches the certificate and configuration for your +domain, does not recognize the license key the container was started with (e.g., because the key was copied incompletely). + + + +**What to do:** copy the Docker command again from the email sent to you at sign-up, as described in +[Signing up: Saving your setup details](getting-started/signing-up.mdx#saving-your-setup-details). +Then remove the container using `docker rm -f quill-` with your container's name instead of `quill-`, and run the command you copied. + + + + + +##### The activation failed + +The terminal prints `Status: FAILED` with `Reason: activation failed; see server logs for details`. + + + +**Likely cause:** an unexpected error stopped the activation. + + + +**What to do:** to find the error that stopped the activation, read `web.log`, using the command shown in +[Starting Quill: When Quill does not come up](getting-started/starting-quill.mdx#when-quill-does-not-come-up). + + + + + +##### Quill is not ready after 180 seconds + +The terminal prints `ERROR: still not ready after 180s.` + + + +**Likely cause:** one of the following may have happened. + + + +* Quill cannot reach `api.ravendb.net` to fetch the certificate and configuration for your domain. + Quill keeps retrying the connection until it succeeds. + To confirm this cause, check whether Quill's container can reach `api.ravendb.net` by running the command below, + with your container's name instead of `quill-`. + The command prints nothing if the connection succeeds, and an error if it fails. + + ```bash + docker exec quill- curl -sS -o /dev/null --max-time 20 https://api.ravendb.net + ``` +
+ + **What to do:** if the command prints an error, allow outgoing HTTPS connections from Quill's machine to `api.ravendb.net`. + Quill's next attempt to connect will then succeed and complete the activation, with no restart, and the terminal + will print `Status: READY`. +* The container was started with a logging setting that Quill cannot use (e.g., a relative log path). + To confirm this cause, read `web.log` using the command shown in + [Starting Quill: When Quill does not come up](getting-started/starting-quill.mdx#when-quill-does-not-come-up), + and look for an error Quill logged while starting, naming a log path, a log level, or the logging configuration. + **What to do:** if such an error appears, correct the setting it names, as described in + [Logging: Troubleshoot startup failures](logging.mdx#troubleshoot-startup-failures). +* The container runs an expired Quill build. Each Quill build expires 90 days after its release date. + To confirm this cause, open the dashboard address, `https://dashboard..myquill.ai`, + with your deployment name instead of ``, in a browser. + An expired build shows a notice titled "Quill needs updating" there, instead of the dashboard. + **What to do:** if the notice appears, replace the container with a container created from a newer Quill image, as + described in + [Updating Quill: Build expiry and license expiry](updating-quill.mdx#build-expiry-and-license-expiry). + + + + + +##### Quill is running but not serving requests + +The terminal prints `Status: DEGRADED - the appliance is not serving requests`. + + + +**Likely cause:** Quill has been activated, but Quill's web application, which serves the management dashboard and the +channels, cannot reach the RavenDB server inside Quill's container. + + + +**What to do:** to find the reason the web application cannot reach the RavenDB server, read the RavenDB server's log, +`ravendb.log`, using this command with your container's name instead of `quill-`: + +```bash +docker exec quill- sh -c "tail -40 /var/lib/quill/logs/ravendb.log" +``` + + + + + +##### The dashboard address does not open + +The browser cannot open the dashboard address, and reports a connection error (e.g., that the connection was closed, reset, or refused). + + + +**Likely cause:** Quill has not been activated yet. Quill accepts connections on port 443 only once the activation is complete. + + + +**What to do:** wait until the terminal prints `Status: READY`, as explained in +[Network Architecture: Why port 443 is unavailable before activation](security-and-architecture/network-architecture.mdx#why-port-443-is-unavailable-before-activation). + + + + + + +Only one key signs you into the management dashboard: the dashboard API key the container was started with, set by +`QUILL_API_KEY` in the [Docker command](getting-started/starting-quill.mdx#running-the-docker-command). +The entries below cover the symptoms that may appear when signing in, and the steps to take when the key is lost or exposed. + + + +##### The API key is not accepted + +Signing in fails with "That API key wasn't accepted. Double-check it and try again." + + + +**Likely cause:** one of the following may have happened. + + + +* The license key was entered instead of the dashboard API key. The email sent at sign-up contains both keys. + **What to do:** enter the dashboard API key, the value that follows `QUILL_API_KEY=` in the Docker command, as explained in + [Operator Authentication: Do not confuse the two signup keys](security-and-architecture/operator-authentication.mdx#do-not-confuse-the-two-signup-keys). +* The container was recreated with a different `QUILL_API_KEY` value (e.g., while updating Quill), so the key you enter is + no longer the key Quill accepts. + **What to do:** sign in with the value the current container was started with, as described in + [Operator Authentication: Finding or recovering your Dashboard API key](security-and-architecture/operator-authentication.mdx#finding-or-recovering-your-dashboard-api-key). +* The container was started without `QUILL_API_KEY`, so Quill accepts no key at all. + **What to do:** recreate the container with the key, as described in + [Operator Authentication: Recreate the container](security-and-architecture/operator-authentication.mdx#recreate-the-container). + + + + + +##### Signing in is refused for a moment + +Signing in fails with "We couldn't sign you in. Please try again in a moment." + + + +**Likely cause:** more than 10 sign-in attempts were made within a minute from your IP address. + + + +**What to do:** wait up to a minute, and then sign in again, as explained in +[Operator Authentication: The sign-in rate limit is per client IP address](security-and-architecture/operator-authentication.mdx#the-sign-in-rate-limit-is-per-client-ip-address). + + + + + +##### The dashboard API key is lost + +**What to do:** find the key in the Docker command the container was started with. +If the container still uses the key issued at sign-up, you can also find the key in the email sent at sign-up, or +[sign up again](https://ravendb.net/quill/start) with the same email address and select your deployment's domain +in the **Quill name** field: RavenDB then shows you the same key again, and emails it to you. +If the key cannot be found, choose a new key and recreate the container with it. +These steps are described in +[Operator Authentication: Finding or recovering your Dashboard API key](security-and-architecture/operator-authentication.mdx#finding-or-recovering-your-dashboard-api-key). + + + + + +##### The dashboard API key was exposed + +The dashboard API key was exposed (e.g., by being pasted into a support ticket). + +**What to do:** choose a new key yourself (a long random value, e.g., one created by a password generator), set it in +`QUILL_API_KEY`, and recreate the container, as described in +[Operator Authentication: Replacing an exposed key](security-and-architecture/operator-authentication.mdx#replacing-an-exposed-key). +The key sent to you at sign-up will no longer sign you into this deployment. + + + +* If the exposed key is the one issued at sign-up, every deployment registered under your email address accepts it: + replace the key in each of them, as described in + [Operator Authentication: Which Quill instances to update](security-and-architecture/operator-authentication.mdx#which-quill-instances-to-update). +* A browser in which someone signed in with the exposed key stays signed in after the key is replaced, until nobody uses + the management dashboard in this browser for eight hours, as explained in + [Operator Authentication: Restarting the container is not enough](security-and-architecture/operator-authentication.mdx#restarting-the-container-is-not-enough). + A browser in which the dashboard stays in use stays signed in. + + + + + + + +##### The old API key still signs in + +The old dashboard API key still signs in after the key was changed. + + + +**Likely cause:** the container was restarted using `docker restart` rather than recreated, so Quill still reads the old key. + + + +**What to do:** recreate the container with the new key, as explained in +[Operator Authentication: Restarting the container is not enough](security-and-architecture/operator-authentication.mdx#restarting-the-container-is-not-enough). + + + + + + + +Quill connects to the source database and lists its tables in the first two stages of the **Add new app** wizard, +as described in [Connecting your database: Connecting to your source database](getting-started/connecting-your-database.mdx#connecting-to-your-source-database). +The symptoms below may appear in these two stages. + + + +##### The connection test fails + +Clicking the `Test connection` button reports that the connection failed. + + + +**Likely cause:** one of the following may have happened. + + + +* `localhost` was entered as the host. Inside Quill's container, `localhost` points at the container itself, so the + connection never reaches a source database outside the container. + **What to do:** enter an address that leads out of the container to the source database's machine, as described in + [Connecting your database: Naming your app and entering the connection details](getting-started/connecting-your-database.mdx#naming-your-app-and-entering-the-connection-details). +* The source database's machine does not accept connections from Quill's machine (e.g., because a firewall blocks the + source database's port). + **What to do:** allow connections from Quill's machine to the port the source database listens on, as described in + [Connecting your database: Prerequisites](getting-started/connecting-your-database.mdx#prerequisites). + + + + + +##### Schema discovery fails + +The `Verify your schema` stage reports "Schema discovery failed", and the table list stays empty. + + + +**Likely cause:** the source database does not meet one of the conditions **CDC (Change Data Capture)** needs +(e.g., a PostgreSQL server whose `wal_level` is not set to `logical`). +The error names the unmet condition, and may carry a statement that fixes it. + + + +**What to do:** have a database administrator run the statement the error carries, or change the setting the error names, +as described for your database type in [Connecting your database: Prerequisites](getting-started/connecting-your-database.mdx#prerequisites). + + + + + +##### The selected tables are refused + +Clicking the `Verify schema` button or the `Next` button of the `Verify your schema` stage reports an error for the selected tables. + + + +**Likely cause:** Quill cannot set up change capture on one of the selected tables, or cannot read from one of them +(e.g., because the database user whose credentials you provided to Quill is not allowed to create the publication through +which a PostgreSQL source database streams the changes). + + + +**What to do:** grant this database user the permission the error names, or have a database administrator run the statement +the error carries. +The permissions each database type requires are listed in +[Connecting your database: Prerequisites](getting-started/connecting-your-database.mdx#prerequisites). + + + + + +##### Tables are missing from the list + +Tables that exist in the source database are not listed in the `Verify your schema` stage. + + + +**Likely cause:** one of the following may have happened. + + + +* The tables belong to a schema other than the connection's default schema (`public` on PostgreSQL), or other + schemas were named in the **Define schemas** side panel, which the stage's **Customize schemas** button opens, so the + default schema is no longer discovered. + + **What to do:** name the schemas the app's tables belong to: + + 1. In the `Verify your schema` stage, click the **Customize schemas** button. + 2. In the **Define schemas** side panel that opens, click **Add schema** for each schema that holds the app's tables, and enter its name. + Add the default schema too, if the app needs its tables. + 3. Click the side panel's **Save & discover** button. + + The side panel is described in [Connecting your database: Choosing the tables](getting-started/connecting-your-database.mdx#choosing-the-tables). +* The database user whose credentials you provided to Quill holds no privilege on the tables. A source database shows + a database user only the tables the user holds a privilege on. + **What to do:** grant this database user the `SELECT` privilege on the tables. + Then click the **Customize schemas** button, and click the side panel's **Save & discover** button to list the tables again. + + + + + +##### A PostgreSQL table is listed with a warning + +A table of a PostgreSQL source database is listed with a warning beside its name. + + + +**Likely cause:** the table has no primary key, or its replica identity is set to `NOTHING`, so PostgreSQL has no columns +with which to tell Quill which row an update or a deletion changed. + + + + + +Once the app is created, Quill adds the table to a publication, the list of tables whose changes PostgreSQL streams to +Quill. From then on, PostgreSQL refuses every `UPDATE` and `DELETE` statement on the table, with an error such as +"cannot delete from table … because it does not have a replica identity and publishes deletes". + + + +**What to do:** before creating the app, have a database administrator run the statement the warning carries +(e.g., `ALTER TABLE . REPLICA IDENTITY FULL;`), or leave the table unselected, as described in +[Connecting your database: Choosing the tables](getting-started/connecting-your-database.mdx#choosing-the-tables). +If the app is already created, running the statement lets the table's updates and deletions succeed again. + + + + + +##### SQL Server Agent is not running + +The `Verify your schema` stage warns that "SQL Server Agent is not running." + + + +**Cause:** the SQL Server Agent service is not running, so the capture tables Quill reads the changes from stay empty, and +Quill will receive no changes until the service runs. + + + +**What to do:** start the SQL Server Agent service. +In an SQL Server Docker container, the service runs only if the container +was started with `MSSQL_AGENT_ENABLED=true`. +The service is described in +[Connecting your database: The SQL Server Agent service](getting-started/connecting-your-database.mdx#the-sql-server-agent-service). + + + + + + + +In the **Map schema** stage of the **Add new app** wizard, you settle a mapping that Quill has drafted, with or without +**AI Suggest**, as described in [Mapping your tables: Settling the mapping](getting-started/mapping-your-tables.mdx#settling-the-mapping). +The symptoms below may appear in this stage, and in the **Preview before full ingest** stage that follows it. + + + +##### AI Suggest fails to draft the mapping + +After the `AI Suggest` option is selected, the `Map schema` stage shows an error message and a `Try again` button instead of the mapping. + + + +**Likely cause:** Quill could not get the mapping from the RavenDB AI service (e.g., because the service could not be reached +from Quill's machine, or did not answer within the time Quill allows the request, five minutes by default). +The error message is the reason the RavenDB AI service gave, or "AI suggestion failed" followed by a status in parentheses. + + + +**What to do:** click the `Try again` button to request the mapping again. +Or, click the wizard's `Back` button, select the **Manual** option in the **How would you like to map your schema?** stage, and draft +the mapping yourself, as described in +[Mapping your tables: Choosing the mapping method: AI Suggest or Manual](getting-started/mapping-your-tables.mdx#choosing-the-mapping-method-ai-suggest-or-manual). + + + + + +##### The `Raw JSON` toggle cannot be switched off + +Switching the `Raw JSON` toggle off is refused with "The raw configuration is not valid JSON.", or with another message that names a problem related to JSON. + + + +**Likely cause:** the mapping's JSON text in the editor is not valid JSON, or does not have the shape of a mapping, an array +with one entry per mapped table. +Until the JSON text is corrected, Quill keeps the last valid mapping, and the stage's `Verify tables` button stays disabled. + + + +**What to do:** correct the mapping's JSON text in the editor, and switch the toggle off again. +The shape of a mapping entry is shown where +the **Raw JSON** toggle is described, in [Mapping your tables: Settling the mapping](getting-started/mapping-your-tables.mdx#settling-the-mapping). + + + + + +##### A JSON column appears as a string + +A column that holds JSON text appears as a string in the documents of the `Preview before full ingest` stage. + + + +**Likely cause:** the column's field mapping is set to the **Default** type, which stores the column's value as it is. + + + +**What to do:** set the column's field mapping to the **JSON** type, which stores the column's JSON text as a nested object: + +1. Click the wizard's `Back` button to return to the **Map schema** stage. +2. In the **Tables** pane, click the table's row to show the table's mapping in the configuration pane. +3. In the configuration pane's **Field mapping** list, find the column's field mapping. + If the list does not show it, click **Show more**. +4. Set the field mapping's **Type** to **JSON**. + +The configuration pane is described in [Mapping your tables: Settling the mapping](getting-started/mapping-your-tables.mdx#settling-the-mapping). + + + + + +##### The preview lacks embedded objects and linked references + +The documents of the `Preview before full ingest` stage carry no embedded objects and no linked references. + + + +**Cause:** the preview builds documents from the selected table's own mapping only, and leaves the tables attached to +it out, as described in [Mapping your tables: Testing your mapping](getting-started/mapping-your-tables.mdx#testing-your-mapping). + + + +**What to do:** no action is needed. +Quill adds the embedded objects and linked references to the documents once the app is +created and the first load runs. + + + + + + + +An AI connection string holds the details through which an agent reaches its LLM: the provider, the model, and the +credentials. +The symptoms below may appear while you add, edit, or delete AI connection strings in the management dashboard's +`AI connection strings` view. + + + +##### Testing or saving a connection string fails + +Clicking the `Test connection` button or the `Save` button reports a failure, in the side panel that opens to add or edit an AI connection string in the `AI connection strings` view. + + + +**Likely cause:** one of the following may have happened. + + + +* Quill could not reach the LLM provider using the entered details, or the selected model cannot complete a request. + **What to do:** correct the settings the reported reason names, as described in + [AI Connection Strings View: Test and save the connection](dashboard/ai-connection-strings.mdx#test-and-save-the-connection). +* The selected model cannot request tools, the capability an agent needs to use its query tools and actions. + Quill then reports that the model "does not support function tools". + **What to do:** select a model that can request tools, as described in + [AI Connection Strings View: Test and save the connection](dashboard/ai-connection-strings.mdx#test-and-save-the-connection). +* The connection string is for Ollama, and its **URI** field points at `localhost`. Inside Quill's container, + `localhost` points at the container itself, so the connection never reaches an Ollama server outside the container. + **What to do:** enter a URI that leads out of the container to the Ollama server, as described in + [AI Connection Strings View: Ollama settings](dashboard/ai-connection-strings.mdx#ollama-settings). + + + + + +##### No models are suggested + +The `Model` field of an AI connection string suggests no models. + + + +**Likely cause:** one of the following may have happened. + + + +* The connection details Quill needs to contact the provider are not entered yet: the API key for OpenAI, the API key + and endpoint for Azure OpenAI, or the URI for Ollama. + **What to do:** enter these details. +* The provider could not be reached, or refused the request (e.g., because the API key is wrong or incomplete, or the + account's quota is used up). + **What to do:** click the `Test connection` button to see the reason the provider gave, and fix the problem it + names (e.g., enter the full API key again, or wait until the account's quota is renewed). + +In either case, you can also type the model's name in the field yourself. +The **Connection details** fields are described in +[AI Connection Strings View: Add an AI connection string](dashboard/ai-connection-strings.mdx#add-an-ai-connection-string). + + + + + +##### Agents answer differently after a connection string was added + +Agents answer differently after a new AI connection string was added. + + + +**Likely cause:** the new connection string was given the name of an existing connection string, and replaced the settings +stored under this name for every agent that uses it. + + + +**What to do:** + +1. In the `AI connection strings` view, click the edit icon in the connection string's row, and restore the replaced + settings. +2. Add the new connection string again, giving it a unique name. + +Adding a connection string is described in +[AI Connection Strings View: Add an AI connection string](dashboard/ai-connection-strings.mdx#add-an-ai-connection-string). + + + + + +##### A connection string cannot be deleted + +The delete icon of an AI connection string is dimmed, and hovering over it shows "Can’t be deleted while in use". + + + +**Cause:** an agent or a task uses the connection string. A connection string cannot be deleted while it is in use. + + + +**What to do:** + +1. In the connection string's row, hover over the badge in the **Used by** column (e.g., "2 uses") to see the agents + and tasks that use the connection string. +2. Switch each such agent or task to another connection string, or delete it. +3. Delete the connection string. + +Switching an agent or a task to another connection string, and deleting one, are described in +[AI Connection Strings View: Delete an AI connection string](dashboard/ai-connection-strings.mdx#delete-an-ai-connection-string). + + + + + + + +An agent's configuration defines the AI connection string through which the agent reaches its LLM, and the query tools and +actions the agent uses to answer your users. +The symptoms below may appear while you set up an agent in the management dashboard, or while an agent answers. + + + +##### The AI options cannot be selected + +The two AI options of the `Create your Agent with AI` stage cannot be selected. + + + +**Likely cause:** the Terms of Use of the RavenDB AI service were not accepted yet. + + + +**What to do:** click the stage's **Review the Terms of Use** button and accept the terms, or set the agent up using the +**Setup manually** option, as described in [Adding an AI agent: Accepting the AI Terms of Use](getting-started/adding-an-ai-agent.mdx#accepting-the-ai-terms-of-use). + + + + + +##### The `Test agent` button is disabled + +The `Test agent` button of an agent's configuration is disabled. + + + +**Likely cause:** the agent's system prompt or connection string is not set. + + + +**What to do:** set both in the **Basic settings** section of the agent's configuration, as described in +[Agents View: The agent's configuration](dashboard/manage-an-app/agents-view.mdx#the-agent-s-configuration). + + + + + +##### An agent cannot be deleted + +Deleting an agent is refused. + + + +**Likely cause:** channels are bound to the agent. + + + +**What to do:** + +1. Open the app's **Channels** view by clicking **Channels** under **Settings** in the app's sidebar. +2. Delete the channels bound to the agent. +3. Delete the agent. + +Deleting an agent is described in [Agents View: Deleting an agent](dashboard/manage-an-app/agents-view.mdx#deleting-an-agent). + + + + + +##### The agent's configuration is refused + +Saving an agent's configuration is refused with "agent configuration rejected; see server logs for details", or testing it with the `Test agent` button shows "Agent test failed. See server logs for details." + + + +**Likely cause:** Quill requires each `$name` placeholder in a query tool's query to be defined by exactly one source, either an +agent parameter or one of the tool's parameters. +The agent's configuration breaks this requirement: in one or more of its queries, a placeholder is defined by neither +source, or by both. + + + +To confirm this cause, run the command below, with your container's name instead of `quill-`. It prints the reason +Quill logged, which names the query tool and the placeholder. + +```bash +docker exec quill- grep -E "contains parameters that are not defined|is defined on both the agent level" /var/lib/quill/logs/web.log +``` +
+ +**What to do**, by the reason the command prints: +* "Tool query '…' contains parameters that are not defined in the agent configuration: '…'" + No source defines the placeholder. + Give it one, in one of these ways: + * Add an agent parameter with the placeholder's name, so that the value is set when a conversation starts. + * Add a parameter with the placeholder's name to the query tool's **Sample parameters object** or **Parameters JSON + schema**, so the LLM will provide the value when it calls the tool. +* "Parameter … is defined on both the agent level and the query level for …" + Both an agent parameter and one of the query tool's parameters define the placeholder. + Remove one of the two. + +Both sources are described in [Agents View: Agent tools](dashboard/manage-an-app/agents-view.mdx#agent-tools). + + + + + +##### An action call failed + +An action call listed in a conversation's transcript returned a response that starts with "action failed:". + + + +**Likely cause:** the call to the outside system failed. The rest of the response names the failure. + + + +**What to do**, by the response: +* "action failed: webhook timed out" + The outside system did not answer within 30 seconds. + Make sure it answers within 30 seconds. +* "action failed: webhook returned" followed by a redirect status (3xx) and a `Location` line + The **Webhook URL** leads to an address that redirects the call, and Quill does not follow redirects. + Set the **Webhook URL** to the address the `Location` line names. +* "action failed: webhook returned" followed by another status code + The outside system answered with a failure status. + Correct the outside system, or the action's settings it rejects. Any reason the outside system gave is included in the + response. +* "action failed:" followed by any other message + Quill could not reach the **Webhook URL** (e.g., because its host name cannot be resolved). + Correct the **Webhook URL**. + +Actions are described in [Agents View: Agent actions](dashboard/manage-an-app/agents-view.mdx#agent-actions). +The conversation's transcript is described in +[Conversations View: The conversation's transcript](dashboard/manage-an-app/conversations-view.mdx#the-conversation-s-transcript). + + + + + +##### An action's response is truncated + +The response of an action, as listed in a conversation's transcript, ends with `[truncated]`. + + + +**Likely cause:** the outside system's response is longer than the action's **Max response size**, 4096 bytes by default. + + + +**What to do:** raise the action's **Max response size**, up to 256 KB, as described in [Agents View: Agent actions](dashboard/manage-an-app/agents-view.mdx#agent-actions). +The conversation's transcript is described in +[Conversations View: The conversation's transcript](dashboard/manage-an-app/conversations-view.mdx#the-conversation-s-transcript). + + + + + + + +Once the app is created, Quill keeps the app's internal database current by mirroring the changes the source database +records. +The app's **Data source** view shows the progress of the mirroring and any errors met while syncing, as described in +[Data Source View: Sync performance](dashboard/manage-an-app/data-source-view.mdx#sync-performance). +To open the view, open the app in the management dashboard and click **Data source** under **Database** in the app's sidebar. + + + +##### The agent answers from outdated information + + + +**Likely cause:** the app's internal database may not hold the latest changes from the source database yet. + + + +**What to do:** check the recent writes and the errors reported in the app's **Data source** view. +Another cause, related to the conversation rather than to mirroring, is described in the "The agent answers from outdated +information" entry in [Channels Overview: Troubleshooting](channels/overview.mdx#troubleshooting). + + + + + +##### Data is missing soon after the app is created + +Soon after the app is created, the agent's answers miss data that exists in the source database. + + + +**Likely cause:** the first load, in which Quill reads the selected tables and builds their documents, is still running in +the background. + + + +**What to do:** wait until the first load completes. +The sync state badge in the app's **Data source** view shows **Active** while +a batch is in progress, and **Idle** once no batch has completed for a minute, as described in +[Data Source View: Sync state](dashboard/manage-an-app/data-source-view.mdx#sync-state). + + + + + +##### Sync errors are detected + +The app's Data source view shows a `Sync errors detected` banner. + + + +**Likely cause:** Quill met errors while reading changes from the source database or while building documents from them +(e.g., because the connection to the source database was lost). + + + +**What to do:** + +1. Click the banner's **View errors** button, and read the errors in the side panel that opens. +2. Correct the cause the errors name. +3. Restart the sync using the **Restart sync** option of the view's three-dot menu. + +Restarting the sync is described in [Data Source View: Restart sync](dashboard/manage-an-app/data-source-view.mdx#restart-sync). + + + + + +##### Sync errors remain listed after the fix + +Sync errors are still listed after their cause was corrected. + + + +**Cause:** Quill does not mark sync errors as resolved, so errors remain listed after their cause is gone. + + + +**What to do:** no action is needed. +Once the cause is corrected, new batches complete successfully, and are marked **Success**. A successful batch shows that +the batch ran without errors, not that every earlier problem is resolved, as explained in +[Data Source View: Sync errors](dashboard/manage-an-app/data-source-view.mdx#sync-errors). + + + + + +##### Sync errors continue after a restart + +Sync errors keep appearing in the app's Data source view after the sync was restarted using the view's `Restart sync` option. + + + +**Likely cause:** the cause named in the sync errors was not corrected yet (e.g., wrong connection settings or table +mappings). + + + +**What to do:** correct the cause the errors name. Connection settings and table mappings are corrected in the **Edit app** +wizard, which the **Edit** option of the view's three-dot menu opens. +Then click the **Restart sync** option of the same menu again, as described in +[Data Source View: Restart sync](dashboard/manage-an-app/data-source-view.mdx#restart-sync). + + + + + +##### No changes arrive from SQL Server + +No changes arrive from an SQL Server source database while its tables change. + + + +**Likely cause:** the SQL Server Agent service is stopped, so the capture tables Quill reads the changes from stay empty. + + + +**What to do:** start the SQL Server Agent service, as described in +[Connecting your database: The SQL Server Agent service](getting-started/connecting-your-database.mdx#the-sql-server-agent-service). + + + + + +##### No changes arrive from MySQL or MariaDB + +No changes arrive from a MySQL or MariaDB source database once the app is created, and sync errors are reported. + + + +**Likely cause:** the database user whose credentials you provided to Quill lacks the `REPLICATION SLAVE` or the +`REPLICATION CLIENT` privilege. Quill needs these privileges only once it starts following the changes, so Quill does not +report their absence before the app is created. + + + +**What to do:** grant both privileges to this database user, as described in +[Connecting your database: Privileges](getting-started/connecting-your-database.mdx#privileges). + + + + + + + +Each channel article ends with a **Troubleshooting** section, listing the symptoms that may appear while setting the channel +up in the management dashboard, or while your users chat through it. +Find the symptoms of each channel type in: + +* [Channels Overview: Troubleshooting](channels/overview.mdx#troubleshooting) + Symptoms common to the Telegram, Slack, and Discord bots, and a symptom that may appear in a channel of any type. +* [Web Widget: Troubleshooting](channels/web-widget.mdx#troubleshooting) + Symptoms that may appear in the management dashboard, and on the website page that embeds the chat box. +* [Telegram Bot: Troubleshooting](channels/telegram-bot.mdx#troubleshooting) + Symptoms that may appear in the management dashboard, and on Telegram. +* [Slack Bot: Troubleshooting](channels/slack-bot.mdx#troubleshooting) + Symptoms that may appear in the management dashboard, in the bot's settings on Slack, and in the Slack client. +* [Discord Bot: Troubleshooting](channels/discord-bot.mdx#troubleshooting) + Symptoms that may appear in the management dashboard, and on Discord. + + + + + +When you sign up, RavenDB adds Quill's hostnames to DNS, the service computers use to find the IP address of a hostname, +and pairs each hostname with the IP address you give for Quill's machine, as described in +[Networking & DNS: The published hostnames](networking-and-dns.mdx#the-published-hostnames). +Each hostname ends with your deployment name and `myquill.ai`, e.g., `dashboard..myquill.ai`, where `` is your +deployment name. +The symptoms below may appear when the IP address of Quill's machine changes, or when users and applications cannot reach +Quill through its hostnames. + + + +##### Quill cannot be reached after an IP change or a move + +After Quill's machine received a new IP address, or you moved Quill to another machine, users and applications can no longer reach Quill through its hostnames. + + + +**Likely cause:** the DNS service still pairs Quill's hostnames with the old address. RavenDB changes these pairs only when +you run the `update-dns` command. + + + +**What to do:** + +1. If you moved Quill to another machine, complete the move: move the data volume to the new machine, and start the new + container with the same `QUILL_LICENSE_KEY` and `QUILL_API_KEY` values, as described in + [Networking & DNS: What remains unchanged](networking-and-dns.mdx#what-remains-unchanged). +2. Run the command below on Quill's machine, with your container's name instead of `quill-` and the machine's new + IP address instead of ``: + + ```bash + docker exec quill- update-dns --ip + ``` +
+ + When the DNS service completes the update, which may take up to 15 minutes, `update-dns` prints + `Successfully registered DNS record(s) for '.myquill.ai' in api.ravendb.net.` + +Updating the records is described in [Networking & DNS: Update the records](networking-and-dns.mdx#update-the-records). + + + + + +##### The IP configuration view's command fails + +The `update-dns` command copied from the `IP configuration` view of the management dashboard fails with "No such container". + + + +**Cause:** in the command the view shows, the container's name is your deployment name (e.g., `baloo`), while the default name the sign-up +Docker command gives the container is `quill-` followed by your deployment name (e.g., `quill-baloo`). + + + +**What to do:** replace the container's name in the copied command with the correct container name, and run the +command again. +To open the view, click **IP configuration** under **Settings** in the management dashboard's sidebar. + + + + + +##### The `update-dns` command times out + +The `update-dns` command fails with "Request failed due to a timeout error". + + + +**Cause:** the DNS service did not confirm the update within 15 minutes, the time limit set in `update-dns`. +The DNS service may still complete the update. + + + +**What to do:** look up Quill's hostnames, using the commands described in +[Networking & DNS: Verify the change](networking-and-dns.mdx#verify-the-change), and check which address the lookups show. +A lookup may show the old address for up to 30 minutes after the update, since the computers and networks answering +lookups may keep a copy of the old address for this long. +If the lookups still show the old address 30 minutes after you ran the `update-dns` command, run the command +again. + + + + + +##### The `update-dns` command fails with another error + + + +**Likely cause:** one of the reasons below, which the error message names. + + + +**What to do**, by the message: +* "Invalid IP address '…'" + The address given after `--ip` is not a valid IPv4 or IPv6 address. + Correct the address, and run the command again. +* "Invalid record '=a,dashboard,db,public,api'" + The address is missing after `--ip`. + Run the command again, with the address after `--ip`. +* Any other message + One of the following may have happened: + * The activated setup package is missing or unreadable. + * Quill's machine does not allow outbound HTTPS connections to `api.ravendb.net`. + * The DNS service rejected the request. + + Follow the checks in the "The DNS update command exits with an error" row of the table in + [Networking & DNS: Diagnose failures](networking-and-dns.mdx#diagnose-failures). + + + + + +##### Some users still reach the old address + +Some users or applications still reach the old address after you updated the DNS records. + + + +**Likely cause:** their computers, or the networks they use, still keep a copy of the old address. RavenDB publishes Quill's +DNS records with a 30-minute limit on how long computers and networks may keep a copy of an address they looked up, and +some browsers and applications may keep their copy of the address even longer. + + + +**What to do:** wait up to 30 minutes. +Restarting an affected browser or application removes its copy of the old address, but a network's copy remains until +the 30 minutes pass. +The 30-minute limit is described in +[Networking & DNS: DNS propagation and TTL](networking-and-dns.mdx#dns-propagation-and-ttl). + + + + + +##### Connections fail although the address is right + +A lookup of one of Quill's hostnames shows the right address, but a connection to the hostname times out, is refused, or fails with a certificate error. + + + +**Likely cause:** one of the following, by what happens to the connection. + + + +* The connection times out: a firewall, cloud security rules, or NAT or load-balancer settings block connections on port + 443 to Quill's machine or its container. + **What to do:** allow inbound connections on port 443 in these settings, and make sure port 443 of the container is + published on Quill's machine. +* The connection is refused: the container is stopped, or its port 443 is not published. + + **What to do**, by the cause: + * If the container is stopped, start it using `docker start quill-`, with your container's name instead of + `quill-`. + * If port 443 is not published: + 1. Make sure the Docker command you copied at sign-up mounts the container's data volume, as described in + [Updating Quill: Identify the container and its data volume](updating-quill.mdx#identify-the-container-and-its-data-volume). + 2. Remove the container using `docker rm -f quill-`, with your container's name instead of `quill-`. + 3. Run the Docker command again. Its `-p 443:443` part publishes port 443. + +
+ + + + A Docker command without the container's data volume starts Quill with a new, empty volume, and the apps are missing. + + + +* The connection fails with a certificate error: the certificate for your domain has expired, e.g., because the RavenDB server + inside Quill's container failed to renew it, or the browser or application connected to an address the certificate + does not cover, such as the IP address of Quill's machine or a hostname of your own. + + **What to do**, by the cause: + * If the browser or application connected to an address the certificate does not cover, use one of Quill's hostnames + in it instead (e.g., `dashboard..myquill.ai`). The certificate covers only hostnames ending with + `..myquill.ai`. + * If the certificate has expired, find the reason its renewal failed, using the command below, with your container's + name instead of `quill-`: + + ```bash + docker exec quill- sh -c "grep -h -A 10 'Failed to replace the server certificate' /var/lib/quill/logs/ravendb-server/*.log" + ``` +
+ + If the log shows failed connections to `api.ravendb.net` or `acme-v02.api.letsencrypt.org`, allow outbound HTTPS + connections from Quill's machine to both. The RavenDB server renews the certificate through the RavenDB service at + `api.ravendb.net` and through Let's Encrypt at `acme-v02.api.letsencrypt.org`. It tries again every hour, with no + restart needed. + +The checks for each case are listed in [Networking & DNS: Diagnose failures](networking-and-dns.mdx#diagnose-failures). + + + + + +##### Data subscriptions cannot connect + +An external application (an application outside Quill) using data subscriptions, or another RavenDB feature requiring a TCP connection, cannot connect to a Quill app's database through `db..myquill.ai`. + + + +**Cause:** external applications connect through `db..myquill.ai` to the RavenDB server inside Quill's container, +which holds the apps' databases, as described in +[Network Architecture: Direct database access](security-and-architecture/network-architecture.mdx#direct-database-access). +The server accepts TCP connections only from inside the container, so external applications can reach it only through its +HTTPS API, on port 443. + + + +**What to do:** in the external application, use features the RavenDB server provides through its HTTPS API (e.g., queries, +and loading and storing documents) instead of features requiring a TCP connection. +Why these features cannot connect from outside Quill's container is described in +[Network Architecture: Native TCP is not exposed](security-and-architecture/network-architecture.mdx#native-tcp-is-not-exposed). + + + + + +##### Access remains after a certificate change + +An external application keeps its access to a Quill app's database after you disabled or deleted its client certificate, or reduced its access. + + + +**Cause:** the RavenDB server inside Quill's container checks the external application's client certificate once, when the +application opens a connection to the server through `db..myquill.ai`, and the access it granted remains in effect +for as long as the connection stays open. + + + +**What to do:** close the external application's connections, or restart the external application. +If the certificate is compromised, close every connection by restarting Quill's container, using +`docker restart quill-` with your container's name instead of `quill-`. + + + +Quill is unavailable while its container restarts: the management dashboard, the apps' databases, and the channels stop +responding until Quill is ready again. + + + +This behavior is described in +[Certificates View: Existing connections are not terminated](dashboard/certificates.mdx#existing-connections-are-not-terminated). + + + + + + + +Each Quill build expires 90 days after its release date. Quill checks the build's age when its container starts, as +described in [Updating Quill: Build expiry and license expiry](updating-quill.mdx#build-expiry-and-license-expiry). +Updating Quill replaces its container with a container created from a newer Quill image, keeping Quill's data as long +as its Docker command mounts the same data volume, as described in +[Updating Quill: What an update replaces](updating-quill.mdx#what-an-update-replaces). +The symptoms below may appear when a build expires, while you update Quill, or when Quill's license expires. + + + +##### The build has expired + +Instead of the management dashboard, the browser shows "Quill needs updating" and "This build has expired." + + + +**Cause:** the container was started from a build released more than 90 days ago. +Quill checks the build's age only when its container starts; a container started before its build expired keeps +working until it restarts (e.g., using `docker restart`, or `docker start` after the container stopped). + + + +Docker still reports the container as healthy, since Quill answers Docker's health check with `expired` and HTTP status 200. +**What to do:** update Quill, replacing the container with a container created from a newer Quill image, as described in +[Updating Quill: Update Quill](updating-quill.mdx#update-quill). +Renewing Quill's license does not help: a build expires 90 days after its release date whatever the license's state, as +explained in [Updating Quill: Build expiry and license expiry](updating-quill.mdx#build-expiry-and-license-expiry). + + + + + +##### The build is still expired after an update + +After you updated Quill, the browser still shows "Quill needs updating". + + + +**Likely cause:** the replacement container was created from the same expired build. One of the following may have happened. + + + +* The Docker command names the image by a version tag (e.g., `ravendb/quill-nightly:7.2.7-quill-nightly-20260924-0326`), + which refers to one specific build. +* The Docker command names the image by the `latest` tag but does not include `--pull=always`, so Docker used the copy + of the image already on Quill's machine instead of downloading the newer image. + +**What to do**, in either case: + +1. Change the Docker command to name the image `ravendb/quill:latest` and include `--pull=always`, like the Docker + command RavenDB sends at sign-up. +2. Make sure the command mounts Quill's data volume, the volume the container used before the update, as described in + [Updating Quill: Identify the container and its data volume](updating-quill.mdx#identify-the-container-and-its-data-volume). +3. Remove the replacement container using `docker stop quill-` and `docker rm quill-`, with your container's + name instead of `quill-`. +4. Run the changed command. + +Refreshing the image is described in [Updating Quill: Refresh the image](updating-quill.mdx#refresh-the-image). + + + + + +##### The container name is already in use + +`docker run` fails with "Conflict. The container name … is already in use". + + + +**Cause:** a container with this name still exists: the old container, or an earlier, unsuccessful replacement. + + + +**What to do:** + +1. Make sure the Docker command mounts Quill's data volume, the volume the container used before the update, as described + in [Updating Quill: Identify the container and its data volume](updating-quill.mdx#identify-the-container-and-its-data-volume). +2. Remove the existing container using `docker stop quill-` and `docker rm quill-`, with your container's + name instead of `quill-`. +3. Run the Docker command again. + +
+ + + +Do not add `-v` to `docker rm`: it removes the container's anonymous volumes, and one of them may hold Quill's data. + + + + + + + +##### Apps are missing after an update + +After you updated Quill, the management dashboard opens, but the apps are missing. + + + +**Likely cause:** the replacement container does not use Quill's data volume. Its Docker command mounts another volume at +`/var/lib/quill`, or mounts none, and Docker created a new, empty volume for the container. + + + + + +Do not add apps or change settings in the new, empty deployment. + + + +**What to do:** stop the replacement container and recreate it with Quill's data volume mounted at `/var/lib/quill`, as +described in [Updating Quill: Recover the recorded data volume](updating-quill.mdx#recover-the-recorded-data-volume). + + + + + +##### The license has expired + +The `License` view shows "This license has expired." + + + +**Cause:** the expiration date of Quill's license, shown in the view, has passed. + + + +**What to do:** contact RavenDB to renew the license: click the view's **Support** button, which opens RavenDB's support +page with the license ID included. +Updating Quill does not renew the license. +To open the view, click **License** under **License & usage** in the management dashboard's sidebar. The view is described +in [License View: Current license](dashboard/license.mdx#current-license). + + + + + + + + + +If none of the entries above solves a problem, contact RavenDB's support. + + + +To open the support page, click **Help center** at the bottom of the management dashboard's sidebar, and then click +**Support**. The support page opens with your license ID included. + +If the management dashboard cannot be opened, go to [ravendb.net/support](https://ravendb.net/support) instead, and enter +your license ID (every Quill deployment has a license, including a deployment you did not purchase). +Use the command below to print your license ID, with your container's name instead of `quill-`: + +```bash +docker exec quill- jq -r .Id /var/lib/quill/setup/license.json +``` + + + +### Collect the details below before contacting support + +A support engineer handling your request will probably ask for the following details. +Run each command on Quill's machine, with your container's name instead of `quill-`. + +* **The symptom** + What you did, what you expected to happen, and the exact message Quill showed or printed. +* **The Quill image the container runs** + + ```bash + docker inspect quill- --format "{{.Config.Image}}" + ``` +
+ +* **The messages Quill printed while starting and running** + + ```bash + docker logs --tail 100 quill- + ``` +
+ +* **Quill's activation state** + Use the command below to print the activation state, e.g., `{"state":"Ready","reason":null}`, and, if the activation + failed, the reason for the failure. + + ```bash + docker exec quill- curl --silent http://127.0.0.1:5000/api/bootstrap/status + ``` +
+ +* **Quill's recent application messages** + + ```bash + docker exec quill- tail -n 200 /var/lib/quill/logs/web.log + ``` +
+ +* **The log of the service the problem concerns** + Each service's log is listed in [Logging: Log locations](logging.mdx#log-locations), e.g., the RavenDB server's own logs + in `/var/lib/quill/logs/ravendb-server/` when the certificate renewal fails. +* **The source database and the LLM provider** + The source database's type and version, when the problem concerns mirroring, and the LLM provider and model the agent + uses, when the problem concerns an agent. + + + +* Read every log before sending it, and remove any details you do not want to share. +* Never send the Docker command, or the output of `docker inspect` run without `--format`: both contain your license key + and your dashboard API key. +* If your dashboard API key was exposed in any way, replace it, as described in + [Operator Authentication: Replacing an exposed key](security-and-architecture/operator-authentication.mdx#replacing-an-exposed-key). + + + + + + From 55a5f4a8b0f7e43a2b92b476d709873542dea713 Mon Sep 17 00:00:00 2001 From: reeb Date: Mon, 28 Sep 2026 14:10:13 +0300 Subject: [PATCH 2/7] RDoc-4117 added /quill/faq --- quill/faq.mdx | 850 ++++++++++++++++++++++++++++++++++++++ quill/troubleshooting.mdx | 5 +- 2 files changed, 853 insertions(+), 2 deletions(-) create mode 100644 quill/faq.mdx diff --git a/quill/faq.mdx b/quill/faq.mdx new file mode 100644 index 0000000000..14b3f05705 --- /dev/null +++ b/quill/faq.mdx @@ -0,0 +1,850 @@ +--- +title: "Quill: FAQ" +sidebar_label: FAQ +sidebar_position: 10 +description: "Questions about Quill, each answered in brief, with a link to the article section that explains the answer in full." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Quill: FAQ + + +* The questions below are answered in brief. Each answer links to the article section that explains it in full. + +* For symptoms that may appear while setting Quill up or running it, and what to do about them, see + [Troubleshooting](troubleshooting.mdx). + +* In this article: + * [About Quill](#about-quill) + * [Trying Quill](#trying-quill) + * [Data and privacy](#data-and-privacy) + * [Mirroring](#mirroring) + * [Agents](#agents) + * [Channels](#channels) + * [Licensing and usage](#licensing-and-usage) + * [Operating Quill](#operating-quill) + + + + + + + + + +##### What is Quill? + + + +Quill is an AI service for your PostgreSQL, SQL Server, MySQL, or MariaDB database, packaged as a single Docker container. +Quill mirrors the tables you select into its internal database: it copies them, and keeps the copy current as your data changes. +Its AI agents can then answer your users' questions from this data. +You can give your users access to Quill's agents through **channels**, such as a Telegram bot, or a chat box on your +website or in your phone app. +Quill is described in full in [Overview: What Quill is](overview.mdx#what-quill-is). + + + + + + + +##### Does Quill change my database? + + + +No, Quill never changes your data. It only [reads the tables you select](overview.mdx#your-sql-database). + +To keep its internal database current, Quill follows the changes your database records. +Turning this +[change recording](getting-started/connecting-your-database.mdx#prerequisites) on changes your database's settings, not +its data: + +* **PostgreSQL:** a database administrator turns change recording on. Quill then sets up the rest in your database, if + the [database user you provide](getting-started/connecting-your-database.mdx#naming-your-app-and-entering-the-connection-details) + has the permission to do so. +* **SQL Server:** Quill turns change recording on in your database, if the database user you provide has the permission + to do so. +* **MySQL and MariaDB:** a database administrator turns change recording on, and Quill only checks it. + + + +* On PostgreSQL, a table without a primary key + [needs one extra step](#what-if-a-postgresql-table-has-no-primary-key) before an app mirrors it. +* On PostgreSQL, while Quill is stopped, your database keeps the changes Quill has not read yet, and they take up disk space on the database's machine. + Quill reads them once it runs again, and PostgreSQL then frees the space. + + + + + + + + + +##### What if a PostgreSQL table has no primary key? + + + +When you [create an app](getting-started/overview.mdx#the-getting-started-steps), Quill asks PostgreSQL to stream the +changes of the tables you selected. PostgreSQL can stream a table's updates and deletions only if it can identify the +rows they change, and a table without a primary key gives it no way to do so. +For such a table, PostgreSQL rejects updates and deletions of its rows. + +To prevent this, Quill shows a warning beside each such table when you +[choose the app's tables](getting-started/connecting-your-database.mdx#choosing-the-tables). +[The warning](troubleshooting.mdx#a-postgresql-table-is-listed-with-a-warning) carries a statement for a database +administrator to run, which makes PostgreSQL identify the table's rows by all their columns. +The administrator can run it before you create the app, or later, if updates and deletions of the table's rows are +already rejected. +Once it runs, updates and deletions work as before. +You can also leave the table out of the app. + + + + + + + +##### Which source databases does Quill support? + + + +PostgreSQL, SQL Server, MySQL, and MariaDB. +Each needs its change recording turned on, and a database user with the +[permissions Quill requires](getting-started/connecting-your-database.mdx#prerequisites). + + + + + + + +##### Can one Quill serve several databases? + + + +Yes. One Quill container can run multiple [apps](overview.mdx#one-quill-several-apps) (e.g., one app for your store and another for your support system). +Each Quill app connects to one source database and keeps its data in an internal database of its own. +Each app also has +its own agents and channels. + + + + + + + +##### Can I work with Quill using code? + + + +Yes. Quill is managed through its management dashboard, and developers can also +[work with it in three ways](overview.mdx#working-with-quill-using-code): + +* **Quill's API** + The API covers Quill's management operations, e.g., connecting a data source, creating agents and channels, and + generating embed links. Quill authenticates API requests with the dashboard API key. +* **The internal database** + Your applications can connect to an app's internal database directly, using a RavenDB client library and a client + certificate you generate in the management dashboard's **Certificates** view. +* **The chat box** + A developer can embed the chat box in a page of your website, or in a phone app, using the HTML segment Quill delivers + for each embed link. + + + + + + + + + + + +##### Can I try Quill on my own machine? + + + +Yes. No separate server is needed: when you sign up, give `127.0.0.1` as the IP address of Quill's machine, and run +Quill with Docker on your own machine. +Your machine still needs the [prerequisites](getting-started/overview.mdx#prerequisites) of any Quill machine, e.g., +internet access and a free port 443. + + + +With `127.0.0.1`, only your own machine can reach Quill: + +* The management dashboard and a [chat box](channels/web-widget.mdx) work in a browser on your machine. +* A [Telegram bot](channels/telegram-bot.mdx) or a [Discord bot](channels/discord-bot.mdx) works for users anywhere. + Quill opens the connection to Telegram or Discord itself, and the users' messages arrive over it. +* A [Slack bot](channels/slack-bot.mdx) does not work, since Slack delivers each message to Quill over the internet. + + + + + + + + + +##### Is there a free trial? + + + +Yes. [Signing up](getting-started/signing-up.mdx#signing-up) starts a 90-day free trial, with no credit card or sales +call required. +For current plan details, see [Quill pricing](https://ravendb.net/quill/pricing). + + + + + + + +##### What runs inside Quill's container, and which ports does it publish? + + + +Quill's container runs +[three main components](security-and-architecture/network-architecture.mdx#what-runs-inside-quill): + +* **[A RavenDB server](overview.mdx#internal-database)**, holding an internal database for each Quill app you create. +* **[The Quill web application](security-and-architecture/network-architecture.mdx#what-runs-inside-quill)**, which + serves the management dashboard, Quill's API, and the channels. +* **[nginx](security-and-architecture/network-architecture.mdx#how-a-connection-is-routed)**, which receives every + connection to Quill and routes it to the RavenDB server or to the web application. + +The container publishes only port 443 on Quill's machine, so 443 is the only port your firewall needs to open for +connections to Quill. + + + + + + + + + + + +##### Which LLM providers can I use? + + + +Quill works with three [LLM providers](getting-started/adding-an-ai-agent.mdx#prerequisites): OpenAI, Azure OpenAI, and +Ollama. +The model you choose must be a chat model able to request tools, since an agent uses tools to query your data and to +call other systems. + + + + + + + +##### Can my users' conversations stay private? + + + +Your users' messages, and the data an agent retrieves to answer them, are sent to the LLM provider the agent uses. +With OpenAI or Azure OpenAI, they reach the provider's servers. +To keep conversations private, use [Ollama](dashboard/ai-connection-strings.mdx#ollama-settings), with a model running on a +machine you control. +RavenDB's AI service receives no conversations, whichever provider you use. + + + + + + + +##### Can data from my database appear in conversations? + + + +Yes. Answering your users from your data is what an agent does: + +1. The agent retrieves data from the app's internal database, using its + [query tools](dashboard/manage-an-app/agents-view.mdx#agent-tools). +2. The agent passes the data to the LLM, which composes the reply. +3. The reply may include the data, and Quill stores the reply with the rest of the conversation. + +An agent can retrieve only the data its query tools return, so the query tools decide which of your data can reach the +LLM provider and the conversations. + + + + + + + +##### What do the AI options send to RavenDB's AI service? + + + +Descriptions of your data, never the data itself. + +* **AI Suggest**, which drafts the mapping when you + [map the app's tables](getting-started/mapping-your-tables.mdx#choosing-the-mapping-method-ai-suggest-or-manual), + sends the structure of the tables you selected: + * The tables' names. + * Their columns. + * Their keys. +* **The two AI options** of the [agent wizard](getting-started/adding-an-ai-agent.mdx#drafting-your-agent), which draft + an agent for you, send: + * The app's mapping, which defines how the tables' rows become documents. + * The description you enter, if you describe the agent you want. + * The names of the app's existing agents, so the drafted agents differ from them. + +These options work only after you accept the +[Terms of Use](getting-started/adding-an-ai-agent.mdx#accepting-the-ai-terms-of-use) of RavenDB's AI service. +Mapping the tables manually, and setting up an agent manually, send nothing to the service. + + + + + + + +##### Are conversations stored, and where can I read them? + + + +Yes. Quill stores each conversation in the app's internal database, and you can read its transcript, including the +messages exchanged and the history of the agent's tool usage, in the app's +[Conversations view](dashboard/manage-an-app/conversations-view.mdx). +The view keeps showing conversations after the agents that held them, or the channels that carried them, are deleted. + + + + + + + +##### How long are conversations kept? + + + +As long as the app exists, unless a user deletes their own conversation: + +* Quill deletes no conversation on its own. +* Conversations cannot be deleted in the Conversations view. +* A user of a [Telegram bot](channels/telegram-bot.mdx#clearing-the-conversation) deletes their conversation by sending + `/clear`. + +[Deleting an app](dashboard/my-apps.mdx#apps) deletes its internal database, including the app's conversations. + + + + + + + +##### Is the data encrypted at rest? + + + +Quill does not encrypt its internal databases. +Quill keeps its data in its [data volume](getting-started/starting-quill.mdx#running-the-docker-command) on Quill's machine. +To encrypt the data at rest, encrypt the disk the volume is stored on. + + + + + + + +##### Can dashboard users see my LLM provider's API key? + + + +Yes. Anyone signed in to the management dashboard can +[reveal the API key](dashboard/ai-connection-strings.mdx#provider-api-keys-can-be-viewed-in-the-dashboard) of an OpenAI or +Azure OpenAI connection string, by clicking the eye icon in the connection string's side panel. +Quill's API returns the key too, to callers using the dashboard API key. + + + +Handle access to the management dashboard as access to these keys. + + + + + + + + + + + + + +##### Does Quill read my whole database? + + + +Only the tables you choose. When you create an app, Quill lists your source database's tables so you can +[choose the app's tables](getting-started/connecting-your-database.mdx#choosing-the-tables). To list them, Quill reads +their names and structure only. +Quill then mirrors the tables you chose, and ignores the others. + + + + + + + +##### How many tables can an app use? + + + +Up to 64 tables. +For more tables, divide them between multiple apps. An agent answers only from its own app's tables, so keep the tables +an agent needs in the same app. + + + + + + + +##### Can I change an app's public URL slug later? + + + +No. Once the app is created, its [public URL slug](getting-started/connecting-your-database.mdx#naming-your-app-and-entering-the-connection-details) +can no longer be changed. +The slug appears in the public URLs the app is served on, and names the app's internal database. + + + + + + + +##### Does deleting an app delete my source database? + + + +No. [Deleting an app](dashboard/my-apps.mdx#apps) deletes the app and its internal database, including the app's agents, +channels, and conversations. Your source database and its data stay as they are. + +The change recording Quill set up in your source database stays in place too: + +* **PostgreSQL:** the publication and the replication slot Quill created to receive the changes remain, named + `rvn_cdc_p_…` and `rvn_cdc_s_…`. +* **SQL Server:** Change Data Capture remains enabled on the database and on the app's tables. +* **MySQL and MariaDB:** Quill [did not set anything up itself](#does-quill-change-my-database), so only the + change-recording settings you set up yourself remain. + + + +On PostgreSQL, a remaining replication slot keeps the database from clearing its change log, so the log keeps growing on +the database's machine. +After deleting an app, have a database administrator remove the app's replication slot, e.g., +using `SELECT pg_drop_replication_slot('rvn_cdc_s_…');` with the slot's name. + + + + + + + + + +##### Do changes in an app's internal database reach my source database? + + + +No. Changes made directly in an app's internal database, e.g., by an application using a RavenDB client, are never +written back to your source database. +When a row changes in your source database, Quill updates the row's document in the internal database, and may +overwrite changes made directly to this document. +Leave the documents Quill creates from your tables for Quill to write, as explained in +[RavenDB Client API Access: Writes do not update the source database](developer-access/ravendb-client-access.mdx#writes-do-not-update-the-source-database). + + + + + + + + + + + +##### Can an agent change my data? + + + +No. An agent reads the app's internal database through its +[query tools](dashboard/manage-an-app/agents-view.mdx#agent-tools), and a query tool can only read: an agent whose query +tool would update or delete documents cannot be saved. Quill never writes to your source database either. +An agent can ask another system to make a change, through an [action](#can-an-agent-call-other-systems) you define. + + + + + + + +##### Can an agent call other systems? + + + +Yes, through the **actions** you define for it. +An action calls a web address you configure, e.g., to open a support ticket, when the LLM decides a conversation requires +this action. +Quill makes the call itself: the LLM cannot reach any system directly, so an agent can call only the addresses its +[actions](dashboard/manage-an-app/agents-view.mdx#agent-actions) define. + + + + + + + +##### Can I test an agent before my users reach it? + + + +Yes. Your users cannot reach an agent until you bind a [channel](channels/overview.mdx) to it, so you can test the agent +first, for as long as you need. +Use the **Test agent** button to chat with the agent: + +* In the wizard, [while you create the agent](getting-started/adding-an-ai-agent.mdx#testing-and-saving-your-agent). +* In the [agent's configuration](dashboard/manage-an-app/agents-view.mdx#the-agent-s-configuration), after the agent is + saved. The chat uses the configuration in the form, unsaved changes included. + +Test chats are not saved, and each message is sent on its own, so the agent does not remember earlier messages. + + + + + + + + + + + +##### Which channel types are there? + + + +Four [channel types](channels/overview.mdx#channel-types): + +* **Web widget:** a chat box on a page of your website, or in a phone app that displays web pages. +* **Telegram bot:** a bot your users chat with on Telegram. +* **Slack bot:** a bot the members of a Slack workspace message directly. +* **Discord bot:** a bot the members of a Discord server message directly. + + + + + + + +##### Do my users need a Quill account? + + + +No. Your users chat with an agent through a channel, and need only what the channel requires, e.g., a Telegram +account to chat with a Telegram bot, or membership in the Slack workspace a Slack bot is installed in. + + + + + + + +##### Can I limit who can chat with an agent? + + + +It depends on the channel type: + +* **Web widget:** anyone who reaches the chat box, on a page of your website or a screen of your phone app, can chat with + the agent. Quill does not identify the chat box's users. + To limit who can chat, place the chat box on pages and screens that only the intended users can reach, e.g., pages + that require signing in to your website. + The channel's **Allowed origins** list names the websites permitted to embed the chat box. However, a user who obtains an + [embed link](channels/web-widget.mdx#generating-an-embed-link) can also open the link directly in a browser and join the + link's conversation, as described in [Web widget: Web widget limitations](channels/web-widget.mdx#web-widget-limitations). +* **Slack bot:** any member of the workspace the bot is installed in can chat with it. +* **Discord bot:** any member of a server the bot is in can chat with it. + The **Public Bot** toggle in the Discord Developer Portal decides who can add the bot to a server, as described in + [Discord bot: Discord bot limitations](channels/discord-bot.mdx#discord-bot-limitations). +* **Telegram bot:** any Telegram user who finds the bot can chat with it. + +A bot channel cannot select users within a Slack workspace, a Discord server, or Telegram. +Agent parameters bound to the user can tie the answers to the user's own data, but cannot turn anyone away. + + + + + + + +##### Can I limit how many questions a user asks? + + + +In a web widget channel, yes. +Each [embed link](channels/web-widget.mdx#setting-the-link-limits) accepts a set number of +user prompts (100 by default), and stops accepting prompts when this number is reached, when the link expires, or when +you revoke the link. +Your backend can generate a separate embed link for each visitor or app user, as described in +[Web widget: Having your backend generate the link](channels/web-widget.mdx#having-your-backend-generate-the-link). +The prompt limit then applies to each visitor's or app user's link separately. + +In addition, Quill accepts up to 60 prompts per minute from each IP address: + +* Prompts sent from the same IP address count toward this limit together, even when they are sent to different channels + or apps. +* Users who connect through the same network, e.g., an office network, may reach Quill from the same IP address, and then + share this limit. + +The Telegram, Slack, and Discord bots set no limit on the number of messages a user sends. + + + + + + + +##### How long does an agent remember a conversation? + + + +It depends on the channel type: + +* **Web widget:** until the embed link the chat box was opened with expires, reaches its prompt limit, or is revoked. +* **Telegram, Slack, and Discord bots:** until midnight UTC. After midnight, the agent answers the next message without + the earlier exchange. + A Telegram user can make the agent forget the earlier exchange sooner, by sending `/clear`. + +The duration of a conversation in each channel type is described in +[Channels Overview: Behavior and limitations common to all channels](channels/overview.mdx#behavior-and-limitations-common-to-all-channels). + +What the agent remembers is separate from what Quill keeps: Quill keeps the conversations, as described in +[How long are conversations kept?](#how-long-are-conversations-kept). + + + + + + + +##### Can I change the agent a channel serves? + + + +No. A channel serves the agent it was added for, as described in +[Channels Overview: Channels and agents](channels/overview.mdx#channels-and-agents). +To have another agent answer your users, add a new channel for the other agent, and then move your users to the new channel: + +* **Web widget:** wherever the chat box is placed, replace the old channel's embed links with links generated for the new + channel. + If your backend generates the embed links, as described in + [Web widget: Having your backend generate the link](channels/web-widget.mdx#having-your-backend-generate-the-link), + have the backend generate links for the new channel. +* **Telegram, Slack, and Discord bots:** to let your users keep chatting with the same bot, connect the bot to the new + channel. + A bot can be connected to one channel only, so delete the old channel first, and then add the new channel with the same + bot. + + + + + + + + + + + +##### What is a WRU, and which writes are measured in WRU? + + + +A WRU (Write Request Unit) is the unit in which Quill's usage is measured and billed. +Each document write is measured as one WRU, whether the write inserts, updates, or deletes a document, and whatever the +document's size is. + +Document writes are made, for example, by: + +* Mirroring: the first copy of your tables, and each later change Quill copies into an app's internal database. +* Quill, when it stores conversation messages. +* Your applications, when they write directly to an app's internal database. + +Reads and queries are not measured in WRU. + +Your usage is shown in the [Usage view](dashboard/usage.mdx) of the management dashboard. The RavenDB server inside +Quill's container reports usage every 15 minutes, so the latest writes may not appear yet. +If you run more than one Quill deployment under the same license, the Usage view shows the usage of all deployments. + +During a free trial period, WRU usage is unlimited. For plan allowances and prices, see +[Quill pricing](https://ravendb.net/quill/pricing). + + + + + + + +##### Do I need a separate RavenDB license? + + + +No. Quill's license covers the RavenDB server inside Quill's container as well. +Quill installs its license when it first starts, using the license key in the Docker command sent to you at sign-up. + +Quill's license includes only the RavenDB features Quill requires, e.g., it does not include read-only client +certificates, as described in +[Certificates View: Read-only access is not available](dashboard/certificates.mdx#read-only-access-is-not-available). + + + + + + + +##### What is the difference between build expiry and license expiry? + + + +They are separate conditions, each requiring a different action: + +* **Build expiry:** each Quill build expires 90 days after its release date. + Quill checks the build's age when its container is started. In a container started from an expired build, the management + dashboard, Quill's API, and the chat boxes all show a notice titled "Quill needs updating" instead of their usual + content. A container that is already running when its build expires keeps running until it restarts. + To replace an expired build, [update Quill](updating-quill.mdx#update-quill) to a newer build. +* **License expiry:** the license's expiration date is shown in the + [License view](dashboard/license.mdx#current-license) of the management dashboard. Once the date has passed, the + License view also shows "This license has expired." + The RavenDB server inside Quill's container checks for a renewed license shortly after it starts and every 24 hours, + and installs a renewed license automatically. + To renew or change the license, [contact RavenDB sales](https://ravendb.net/contact). + +Updating Quill does not renew the license, and renewing the license does not reset the build's 90 days. + + + + + + + + + + + +##### Where are Quill's logs? + + + +Quill writes its startup and readiness messages to the container's output, which `docker logs` shows. +The other logs are files inside Quill's container, under `/var/lib/quill/logs`. For example, `web.log` holds Quill's +application messages, including agent and chat activity. + +The log files are kept in Quill's data volume, so they remain when you [update Quill](updating-quill.mdx#update-quill) +and the new container mounts the same volume. +Each log and its contents are listed in [Logging: Log locations](logging.mdx#log-locations). + + + + + + + +##### Does updating Quill delete my data? + + + +No, as long as the new container mounts the same data volume. +Updating Quill replaces its container with a container created from a newer image. Quill keeps its data (e.g., your +apps, their internal databases, and the conversations) in a Docker volume mounted at `/var/lib/quill`, and removing the +old container leaves this volume in place. + + + +* Before removing the old container, find the data volume the container mounts at `/var/lib/quill`, and make sure the + new container mounts the same volume, as described in + [Updating Quill: Identify the container and its data volume](updating-quill.mdx#identify-the-container-and-its-data-volume). +* A new container that does not mount this volume starts without your apps. The data remains in the old volume, and returns + once a container mounts this volume again, as described in + [Updating Quill: Recover the recorded data volume](updating-quill.mdx#recover-the-recorded-data-volume). +* Remove the old container using plain `docker rm`, without `-v`: with `-v`, Docker also deletes a data volume that was + created without a name. + + + + + + + + + +##### Do I need a new domain or certificate when the IP address of Quill's machine changes? + + + +No. Quill's domain, hostnames, certificate, keys, and data stay as they are, since none of them depends on the IP address. + +Only the DNS records change. DNS is the service computers use to find the IP address of a hostname, and Quill's DNS +records pair each of Quill's hostnames with the IP address of Quill's machine. +To pair the hostnames with the new address, run the `update-dns` command in Quill's container, as described in +[Networking & DNS: Update the records](networking-and-dns.mdx#update-the-records). Until you run the command, users +and applications keep reaching the old address. + +If you move Quill to another machine, also move Quill's data volume to the new machine, and start the new container with +the same license key and dashboard API key, as described in +[Networking & DNS: What remains unchanged](networking-and-dns.mdx#what-remains-unchanged). + + + + + + + +##### Can I have separate operator accounts? + + + +No. Quill has a single operator credential: the dashboard API key. +Anyone who has the key has full access to the management dashboard and to Quill's API, and Quill cannot identify the +person who performed an action. + +To stop someone who knows the key from signing in, replace the key, as described in +[Operator Authentication: Replacing an exposed key](security-and-architecture/operator-authentication.mdx#replacing-an-exposed-key). +Replacing the key does not end the sessions opened with the old key, as described in +[How long does a dashboard session last?](#how-long-does-a-dashboard-session-last). + + + + + + + +##### How long does a dashboard session last? + + + +Until 8 hours pass without activity in the management dashboard. Each time you use the dashboard, the 8-hour period +starts again. + +* Signing out ends the session in the browser you sign out from. +* Replacing the dashboard API key does not end the sessions opened with the old key. Each of these sessions remains + valid until 8 hours pass without activity in it. + +Dashboard sessions are described in +[Operator Authentication: Signing in to the dashboard](security-and-architecture/operator-authentication.mdx#signing-in-to-the-dashboard). + + + + diff --git a/quill/troubleshooting.mdx b/quill/troubleshooting.mdx index 90fcba38fe..92d30235ca 100644 --- a/quill/troubleshooting.mdx +++ b/quill/troubleshooting.mdx @@ -426,8 +426,9 @@ with which to tell Quill which row an update or a deletion changed. Once the app is created, Quill adds the table to a publication, the list of tables whose changes PostgreSQL streams to -Quill. From then on, PostgreSQL refuses every `UPDATE` and `DELETE` statement on the table, with an error such as -"cannot delete from table … because it does not have a replica identity and publishes deletes". +Quill. From then on, PostgreSQL rejects `UPDATE` and `DELETE` statements on the table, with an error such as +"cannot delete from table … because it does not have a replica identity and publishes deletes", until a database +administrator runs the statement described below. From d319edc58c40e6e4bce3b68ce46a0b08cac84491 Mon Sep 17 00:00:00 2001 From: reeb Date: Tue, 29 Sep 2026 14:07:24 +0300 Subject: [PATCH 3/7] RDoc-4067, RDoc-4117 - updates and fixes in Quill pages --- quill/channels/discord-bot.mdx | 292 +++++++++++----- quill/channels/overview.mdx | 99 ++++-- quill/channels/slack-bot.mdx | 321 +++++++++++++----- quill/channels/telegram-bot.mdx | 285 ++++++++++++---- quill/channels/web-widget.mdx | 209 +++++++++--- quill/dashboard/ip-configuration.mdx | 8 +- quill/dashboard/manage-an-app/agents-view.mdx | 66 +++- .../manage-an-app/conversations-view.mdx | 3 +- .../manage-an-app/data-source-view.mdx | 2 +- quill/dashboard/manage-an-app/overview.mdx | 2 +- quill/dashboard/my-apps.mdx | 2 +- .../ravendb-client-access.mdx | 17 +- quill/faq.mdx | 151 ++++---- quill/getting-started/adding-an-ai-agent.mdx | 19 +- .../assets/sign-up_ready-to-start.png | Bin 225025 -> 193585 bytes .../snagit/sign-up_ready-to-start.snagx | Bin 701512 -> 359876 bytes .../connecting-your-database.mdx | 61 ++-- quill/getting-started/overview.mdx | 2 +- quill/getting-started/starting-quill.mdx | 13 +- quill/home.mdx | 6 +- quill/networking-and-dns.mdx | 26 +- quill/overview.mdx | 8 +- .../network-architecture.mdx | 11 +- .../operator-authentication.mdx | 10 +- quill/troubleshooting.mdx | 287 +++++++++++----- quill/updating-quill.mdx | 3 +- 26 files changed, 1353 insertions(+), 550 deletions(-) diff --git a/quill/channels/discord-bot.mdx b/quill/channels/discord-bot.mdx index 69c87ffedf..437d2afa74 100644 --- a/quill/channels/discord-bot.mdx +++ b/quill/channels/discord-bot.mdx @@ -466,9 +466,9 @@ The limits below follow this design and Discord's own rules. None of them can be * Any member of a server the bot was invited to can open a direct message with the bot and ask it questions. * Agent parameters bound to the Discord user can tie the answers to this user's own data, but cannot turn anyone away. - What you do control is which servers the bot is added to. The **Public Bot** toggle on the app's Bot page in the Discord Developer - Portal decides who can add the bot to a server: when the toggle is on, as it is by default, anyone who has the invite link can add - the bot to a server that this person manages; when the toggle is off, only you can. + What you do control is which servers the bot is added to. To be the only one who can add the bot to a server, turn off the + **Public Bot** toggle on the app's Bot page in the Discord Developer Portal. + While the toggle is on, as it is by default, anyone who has the invite link can add the bot to a server that this person manages. * **The bot answers in direct messages only.** A message posted in one of the server's chat rooms, such as #general, where every member can read it, gets no reply, even if the message mentions the bot. @@ -490,99 +490,235 @@ The limits below follow this design and Discord's own rules. None of them can be - - Symptoms met by the users of every bot type, not just of a Discord bot, are listed in the channels overview, in [Troubleshooting](../channels/overview.mdx#troubleshooting). - - The symptoms below are shown by a Discord bot channel when something goes wrong, each with its likely cause and what to do about it. The first symptoms are seen in Quill's management dashboard: in the channel form, in the **Edit channel** form, and in the channel's [Connect](#the-connect-tab) tab. The rest are encountered by the bot's users on Discord, in the server's chat rooms or in their direct messages with the bot. - +--- ### In the dashboard -* **Clicking `Connect bot` fails with "discord rejected the bot token".** - Likely cause: the token pasted in the form may be incomplete or mistyped, or a newer token may have been issued for the bot in the - Discord Developer Portal, so this one is no longer accepted. - What to do: whichever the cause, reset the token, since the Discord Developer Portal shows a token only once: open the app's Bot - page there, click **Reset Token**, and paste the new token in the form's [Bot token](#filling-in-the-channel-form) field. -* **Clicking `Connect bot` fails with "that token belongs to a user account, not a bot".** - Likely cause: the pasted token may be the token of a Discord user account rather than the bot's. - What to do: copy the token from the app's Bot page in the Discord Developer Portal, as described in - [Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal). -* **Clicking `Connect bot` fails with "Discord bot ... is already connected".** - Likely cause: the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve - only one channel. When the channel is in another app, the message names that app. - What to do: delete the channel that holds the bot, in this app or in the app the message names, as described in - [Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another application, with its own bot, in the - Discord Developer Portal, as described in - [Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal), and paste the new bot's token in - this form instead. -* **Clicking `Save changes` in the `Edit channel` form fails with "the token belongs to a different bot".** - Likely cause: the new token may have been copied from the Bot page of a different application in the Discord Developer Portal. - What to do: copy the token from the Bot page, in the Discord Developer Portal, of the application whose bot the channel was created - for. - To switch to a different bot, add a new channel for that bot instead, as described in - [Connecting the bot to your app](#connecting-the-bot-to-your-app). -* **The `Connect` tab shows "Token rejected", and the bot does not answer.** - Likely cause: the token may have been reset in the Discord Developer Portal, so Discord no longer accepts it. - The bot is offline on Discord, and messages users send meanwhile do not reach Quill and are not answered later. - - ![The Connect tab with a rejected token](./assets/discord-bot_token-rejected.png) - - What to do: if you hold the token issued at the reset, enter it in the channel, as described in - [Rotating the bot token](#rotating-the-bot-token). If you do not, click **Reset Token** on the app's Bot page in the Discord - Developer Portal, and enter the token it shows in the channel the same way. -* **The `Connect` tab shows "Gateway disconnected" or "Connecting...", and the bot does not answer.** - Likely cause: Quill may be unable to reach Discord. The red alert under the connection card in the Connect tab quotes the error - Quill received. - The bot needs the machine running Quill to have access to `discord.com` and `gateway.discord.gg`, as described in - [Prerequisites](#prerequisites); a firewall or a proxy blocking these addresses is the usual cause. - What to do: allow outgoing HTTPS connections from the machine running Quill to these two addresses in the firewall or proxy that - blocks them, or ask your network administrator to. Quill reconnects on its own, within a few minutes of the access returning. -* **The `Connect` tab shows "Paused", and the bot does not answer.** - Likely cause: the channel was paused, using **Pause** in the header of its details view. - Messages users send while the channel is paused do not reach Quill and are not answered later. - What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). -* **The `Connect` tab shows a red alert, "Last reply could not be delivered", under the connection card.** - Likely cause: Discord may have refused to deliver the bot's last reply. The alert quotes Discord's error; the usual reason is that - the user can no longer receive messages from the bot, because the user left the server the bot is in, blocked the bot, or turned - off direct messages from server members in Discord's **Privacy & Safety** settings. - The alert does not name the user; most likely, it is the user whose message arrived last, at the time shown under - **Last message**. - What to do: the fix is on the user's side. Advise the user to undo whichever of these applies: rejoin the server, unblock the bot, - or allow direct messages from server members again. + + +##### Discord rejects the bot token + +Clicking `Connect bot` fails with `discord rejected the bot token`. + + + +**Likely cause:** the token pasted in the form may be incomplete or mistyped, or a newer token may have been issued for the bot in the +Discord Developer Portal, so this one is no longer accepted. + + + +**What to do:** whichever the cause, reset the token, since the Discord Developer Portal shows a token only once: open the app's Bot +page there, click **Reset Token**, and paste the new token in the form's [Bot token](#filling-in-the-channel-form) field. + + + + + +##### The token belongs to a user account, not to a bot + +Clicking `Connect bot` fails with `that token belongs to a user account, not a bot`. + + + +**Likely cause:** the pasted token may be the token of a Discord user account rather than the bot's. + + + +**What to do:** copy the token from the app's Bot page in the Discord Developer Portal, as described in +[Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal). + + + + + +##### The bot is already connected + +Clicking `Connect bot` fails with `Discord bot ... is already connected`. + + + +**Cause:** the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve +only one channel. When the channel is in another app, the message names that app. + + + +**What to do:** delete the channel that holds the bot, in this app or in the app the message names, as described in +[Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another application, with its own bot, in the +Discord Developer Portal, as described in +[Creating a bot in the Discord Developer Portal](#creating-a-bot-in-the-discord-developer-portal), and paste the new bot's token in +this form instead. + + + + + +##### The new token belongs to a different bot + +Clicking `Save changes` in the `Edit channel` form fails with `the token belongs to a different bot`. + + + +**Likely cause:** the new token may have been copied from the Bot page of a different application in the Discord Developer Portal. + + + +**What to do:** copy the token from the Bot page, in the Discord Developer Portal, of the application whose bot the channel was created +for. +To switch to a different bot, add a new channel for that bot instead, as described in +[Connecting the bot to your app](#connecting-the-bot-to-your-app). +##### The bot's token is rejected + +The `Connect` tab shows `Token rejected`, and the bot does not answer. + + + +**Likely cause:** the token may have been reset in the Discord Developer Portal, so Discord no longer accepts it. +The bot is offline on Discord, and messages users send meanwhile do not reach Quill and are not answered later. + + + +![The Connect tab with a rejected token](./assets/discord-bot_token-rejected.png) + +**What to do:** if you hold the token issued at the reset, enter it in the channel, as described in +[Rotating the bot token](#rotating-the-bot-token). If you do not, click **Reset Token** on the app's Bot page in the Discord +Developer Portal, and enter the token it shows in the channel the same way. + + + + + +##### The bot is disconnected from Discord + +The `Connect` tab shows `Gateway disconnected` or `Connecting...`, and the bot does not answer. + + + +**Likely cause:** Quill may be unable to reach Discord. The red alert under the connection card in the Connect tab quotes the error +Quill received. +The bot needs the machine running Quill to have access to `discord.com` and `gateway.discord.gg`, as described in +[Prerequisites](#prerequisites); a firewall or a proxy blocking these addresses is the usual cause. + + + +**What to do:** allow outgoing HTTPS connections from the machine running Quill to these two addresses in the firewall or proxy that +blocks them, or ask your network administrator to. Quill reconnects on its own, within a few minutes of the access returning. + + + + + +##### The channel is paused + +The `Connect` tab shows `Paused`, and the bot does not answer. + + + +**Cause:** the channel was paused, using **Pause** in the header of its details view. +Messages users send while the channel is paused do not reach Quill and are not answered later. + + + +**What to do:** resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + + + + +##### The bot's last reply could not be delivered + +The `Connect` tab shows a red alert, `Last reply could not be delivered`, under the connection card. + + + +**Likely cause:** Discord may have refused to deliver the bot's last reply. The alert quotes Discord's error; the usual reason is that +the user can no longer receive messages from the bot, because the user left the server the bot is in, blocked the bot, or turned +off direct messages from server members in Discord's **Privacy & Safety** settings. +The alert does not name the user; most likely, it is the user whose message arrived last, at the time shown under +**Last message**. + + + +**What to do:** the fix is on the user's side. Advise the user to undo whichever of these applies: rejoin the server, unblock the bot, +or allow direct messages from server members again. + + + +--- + ### On Discord -* **A user cannot find the bot, or cannot open a direct message with it.** - Likely cause: the user may not be a member of the server the bot was invited to. On Discord, a user can message a bot only if the - user and the bot are both members of the same server. - What to do: invite the bot to a server the user is a member of, using the invite link in the [Connect](#the-connect-tab) tab, or - advise the user to join the server the bot is in. Then advise the user to open a direct message with the bot, as described in - [Finishing the connection on Discord](#finishing-the-connection-on-discord). -* **The bot does not reply to a message a user posted in one of the server's chat rooms.** - Likely cause: the bot reads only the direct messages sent to it. A message posted in one of the server's chat rooms, such as - #general, where every member can read it, does not reach the bot, even if the message mentions the bot. - What to do: advise the user to send the question in a direct message with the bot, opened as described in - [Finishing the connection on Discord](#finishing-the-connection-on-discord). -* **The bot replies "Sorry - something went wrong handling that message. Please try again."** - Likely cause: either the agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel - was added, or the agent failed to answer, e.g., because the database it queries or the LLM service it uses could not be reached. - What to do: if a parameter is shown unbound in the channel's [Parameters](#the-parameters-tab) tab, bind it. If every parameter is - bound, the agent itself failed to produce the answer: verify that the app's database, and the LLM service behind the agent's AI - connection string, can be reached. The connection string can be tested as described in - [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then send the bot a - question again. + + +##### A user cannot find the bot or message it + +A user cannot find the bot, or cannot open a direct message with it. + + + +**Likely cause:** the user may not be a member of the server the bot was invited to. On Discord, a user can message a bot only if the +user and the bot are both members of the same server. + + + +**What to do:** invite the bot to a server the user is a member of, using the invite link in the [Connect](#the-connect-tab) tab, or +advise the user to join the server the bot is in. Then advise the user to open a direct message with the bot, as described in +[Finishing the connection on Discord](#finishing-the-connection-on-discord). + + + + + +##### The bot does not reply in a chat room + +The bot does not reply to a message a user posted in one of the server's chat rooms. + + + +**Cause:** the bot reads only the direct messages sent to it. A message posted in one of the server's chat rooms, such as +#general, where every member can read it, does not reach the bot, even if the message mentions the bot. + + + +**What to do:** advise the user to send the question in a direct message with the bot, opened as described in +[Finishing the connection on Discord](#finishing-the-connection-on-discord). + + + + + +##### The bot reports that something went wrong + +The bot replies `Sorry - something went wrong handling that message. Please try again.` + + + +**Likely cause:** one of the following may have happened. + + + +* The agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel was added. +* A parameter is bound to a value the agent parameter's type no longer accepts, e.g., because the type was changed in the + agent after the channel was added. +* The agent failed to answer, e.g., because the database it queries or the LLM service it uses could not be reached. + +**What to do:** if a parameter is shown unbound in the channel's [Parameters](#the-parameters-tab) tab, bind it. If an agent +parameter's type was changed, bind the parameter again in the Parameters tab, with a value or a source that matches the type. If +every parameter is bound, the agent itself failed to produce the answer: verify that the app's database, and the LLM service +behind the agent's AI connection string, can be reached. The connection string can be tested as described in [Dashboard: AI +connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then send the bot a question again. diff --git a/quill/channels/overview.mdx b/quill/channels/overview.mdx index 221ad9fb07..72655d8157 100644 --- a/quill/channels/overview.mdx +++ b/quill/channels/overview.mdx @@ -117,7 +117,8 @@ Agent parameters are bound by the channel, and the source of a parameter's value * **Users need no account with Quill.** Who can reach a channel depends on the channel type: - * A web widget channel is reached by any visitor to a website page that holds one of the channel's embed links. + * A web widget channel is reached by any website visitor or phone app user who opens a chat box using one of the channel's + embed links. * A Telegram bot is reached by any Telegram user who finds the bot. * A Slack bot is reached by the members of the workspace the bot is installed in. * A Discord bot is reached by the members of a server the bot is in. @@ -140,7 +141,7 @@ Agent parameters are bound by the channel, and the source of a parameter's value chat. A Telegram user can make the agent forget sooner by sending `/clear`; Slack and Discord users cannot. * In a web widget channel, the conversation belongs to the embed link that opened the chat box, and lasts as long as the link is valid: - all website visitors who open the chat box through the same link share the same conversation, which ends when + all users who open the chat box through the same link share the same conversation, which ends when the link [expires, reaches its chat limit, or is revoked](../channels/web-widget.mdx#invalid-links). * **Messages sent faster than the bot answers may go unanswered.** On Telegram, Slack, and Discord, a message a user sends while the bot is still answering waits in a queue that Quill keeps for @@ -169,34 +170,72 @@ Agent parameters are bound by the channel, and the source of a parameter's value The symptoms below may be met by a channel's users, each with its likely cause and what to do about it. The bots' messages are quoted in their default form; a Telegram bot with customized messages shows your texts instead. -**In a chat with a Telegram, Slack, or Discord bot** - -* **The bot does not reply to a photo or a file, or replies "I can only read text messages right now."** - Likely cause: the bots answer text-only messages, as stated in - [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels), and the user's message may - carry a file, like an image or a document. A Telegram bot gives such a message no reply; a Slack or Discord bot answers with the - quoted notice. - What to do: advise the user to send the question as text. - A chat box takes text only, so its users do not meet this symptom. -* **The bot replies "I'm still working through your earlier messages, so that one didn't make it. Please resend it once I've - replied."** - Likely cause: the user may have sent more messages than the bot's queue can hold while an answer was still being composed, as - stated in [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). - What to do: advise the user to wait for the bot's reply, and then send the message again. - A chat box takes no new message while the agent is still answering, so its users do not meet this symptom. - -**In a channel of any type** - -* **The agent answers from outdated information.** - Likely cause: one of the following may have happened. - * The app's internal database may not yet hold the latest changes from the source database. - What to do: check the state of the mirroring in the app's **Data source** view, which shows the number of recent writes and - reports any errors met while syncing. - * The conversation may hold earlier replies carrying data the agent had retrieved, that the agent now reads instead of - retrieving the data again. - What to do: a message that asks pointedly for the current data may make the agent retrieve it again. - In any case, the agent retrieves the data again once it forgets the earlier exchange, as described in - [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). +--- + +### In a chat with a Telegram, Slack, or Discord bot + + + +##### The bot does not reply to a photo or a file + +The bot does not reply to a photo or a file, or replies `I can only read text messages right now.` + + + +**Likely cause:** the bots answer text-only messages, as stated in +[Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels), and the user's message may +carry a file, like an image or a document. A Telegram bot gives such a message no reply; a Slack or Discord bot answers with the +quoted notice. + + + +**What to do:** advise the user to send the question as text. +A chat box takes text only, so its users do not meet this symptom. + + + + + +##### The bot asks to resend a message + +The bot replies `I'm still working through your earlier messages, so that one didn't make it. Please resend it once I've replied.` + + + +**Likely cause:** the user may have sent more messages than the bot's queue can hold while an answer was still being composed, as +stated in [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). + + + +**What to do:** advise the user to wait for the bot's reply, and then send the message again. +A chat box takes no new message while the agent is still answering, so its users do not meet this symptom. + + + +--- + +### In a channel of any type + + + +##### The agent answers from outdated information + + + +**Likely cause:** one of the following may have happened. + + + +* The app's internal database may not yet hold the latest changes from the source database. + **What to do:** check the state of the mirroring in the app's **Data source** view, which shows the number of recent writes and + reports any errors met while syncing. +* The conversation may hold earlier replies carrying data the agent had retrieved, that the agent now reads instead of + retrieving the data again. + **What to do:** a message that asks pointedly for the current data may make the agent retrieve it again. + In any case, the agent retrieves the data again once it forgets the earlier exchange, as described in + [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). + + Symptoms specific to a channel type, including those seen in Quill's management dashboard and on the bot's platform, are listed in the Troubleshooting section of the type's article: [Telegram bot](../channels/telegram-bot.mdx#troubleshooting), diff --git a/quill/channels/slack-bot.mdx b/quill/channels/slack-bot.mdx index 8dea43e5a6..a4e00c4da7 100644 --- a/quill/channels/slack-bot.mdx +++ b/quill/channels/slack-bot.mdx @@ -604,123 +604,262 @@ The limits below follow this design and Slack's own rules. None of them can be c - - Symptoms met by the users of every bot type, not just of a Slack bot, are listed in the channels overview, in [Troubleshooting](../channels/overview.mdx#troubleshooting). - - The symptoms below are shown by a Slack bot channel when something goes wrong, each with its likely cause and what to do about it. The first symptoms are seen in Quill's management dashboard: in the channel form and in the channel's [Connect](#the-connect-tab) tab. One symptom is seen in the bot's settings on Slack, on the **Event Subscriptions** page. The rest are encountered by the bot's users in the Slack client. - +--- ### In the dashboard -* **The `Bot token` field reports "The bot token starts with xoxb- (not a user or app-level token)".** - Likely cause: the pasted token may be the **App token** (`xapp-...`) shown next to the bot token on the **Quill is ready!** page - on Slack. - What to do: copy the **Bot User OAuth Token** from the bot's **OAuth & Permissions** page on Slack, as described in - [Collecting the bot token and the signing secret](#collecting-the-bot-token-and-the-signing-secret), and paste it in the field. -* **Clicking `Connect bot` fails with "slack rejected the bot token".** - Likely cause: the token pasted in the form may be incomplete or mistyped, or it may have been revoked on Slack since it was - copied. - What to do: copy the **Bot User OAuth Token** from the bot's OAuth & Permissions page on Slack again, and paste it in the form's - [Bot token](#filling-in-the-channel-form) field. If the bot was uninstalled, reinstall it from the same page first. -* **Clicking `Connect bot` fails with "slack is rate-limiting the token check" or "could not reach the Slack API".** - Likely cause: Slack may be limiting Quill's requests for a moment, or the machine that runs Quill may be unable to reach - `slack.com`. - What to do: wait a minute or two and try again. If the failure persists, verify that the machine that runs Quill can open HTTPS - connections to `slack.com`, as described in [Prerequisites](#prerequisites). -* **Clicking `Connect bot` fails with "Slack bot ... is already connected".** - Likely cause: the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve - only one channel. When the channel is in another app, the message names that app. - What to do: delete the channel that holds the bot, in this app or in the app the message names, as described in - [Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another bot from the manifest, with a name of its - own, as described in [Creating a Slack bot from Quill's manifest](#creating-a-slack-bot-from-quill-s-manifest), and paste the new - bot's credentials in this form instead. -* **The `Connect` tab shows "Token rejected", and the bot does not answer.** - Likely cause: the bot's token may have been revoked on Slack, by **Revoke All OAuth Tokens** on its OAuth & Permissions page or by - uninstalling the bot from the workspace. - The users' messages still reach Quill, but the bot cannot post its replies, so the messages are not answered, and are not answered - later. Quill re-checks the token every few minutes, so the badge may turn red a few minutes after the revocation. The tab then - also shows the red alert "The bot couldn't deliver a reply" under the connection card, which remains until Quill is restarted. - - ![The Connect tab with a rejected token](./assets/slack-bot_token-rejected.png) - - What to do: reinstall the bot from its OAuth & Permissions page on Slack, copy the new **Bot User OAuth Token** the page then - shows, and enter it in the channel, as described in [Rotating the credentials](#rotating-the-credentials). -* **The `Connect` tab shows a red alert, "A delivery failed signature verification", under the connection card.** - Likely cause: the signing secret held by the channel may differ from the bot's: the secret may have been regenerated on Slack, - or mistyped when the channel was added. - Quill rejects the deliveries it cannot verify, so the users' messages are not answered until the secrets match. - - ![The Connect tab with a failed signature verification](./assets/slack-bot_signature-failed.png) - - What to do: copy the **Signing Secret** from the **App Credentials** section of the bot's **Basic Information** page on Slack, and - enter it in the channel, as described in [Rotating the credentials](#rotating-the-credentials). The alert disappears once a - delivery is verified. -* **The `Connect` tab shows "Token valid", but "Last message" does not change when users message the bot, and the bot does not - answer.** - Likely cause: Slack may not be delivering the messages to Quill: the event subscription may be incomplete, the request URL may - have failed Slack's verification, or the deployment may no longer be reachable from the internet. - What to do: open the bot's **Event Subscriptions** page on Slack and check that **Enable Events** is on, that the **Request URL** - is marked **Verified**, that `message.im` is listed under **Subscribe to bot events**, and that the changes were saved, as - described in [Finishing the event subscription on Slack](#finishing-the-event-subscription-on-slack). If the URL is not verified, - see the "Your URL didn't respond." entry below. -* **The `Connect` tab opens with "This channel is paused, so the bot isn't answering right now."** - Likely cause: the channel was paused, using **Pause** in the header of its details view. - Messages users send while the channel is paused do not reach the agent and are not answered later. - What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + +##### The token is not a bot token + +The `Bot token` field reports `The bot token starts with xoxb- (not a user or app-level token)`. + + + +**Likely cause:** the pasted token may be the **App token** (`xapp-...`) shown next to the bot token on the **Quill is ready!** page +on Slack. + + + +**What to do:** copy the **Bot User OAuth Token** from the bot's **OAuth & Permissions** page on Slack, as described in +[Collecting the bot token and the signing secret](#collecting-the-bot-token-and-the-signing-secret), and paste it in the field. -### In the bot's settings on Slack +##### Slack rejects the bot token + +Clicking `Connect bot` fails with `slack rejected the bot token`. + + + +**Likely cause:** the token pasted in the form may be incomplete or mistyped, or it may have been revoked on Slack since it was +copied. + + + +**What to do:** copy the **Bot User OAuth Token** from the bot's OAuth & Permissions page on Slack again, and paste it in the form's +[Bot token](#filling-in-the-channel-form) field. If the bot was uninstalled, reinstall it from the same page first. + + + + + +##### Quill cannot verify the token with Slack + +Clicking `Connect bot` fails with `slack is rate-limiting the token check` or `could not reach the Slack API`. + + + +**Likely cause:** Slack may be limiting Quill's requests for a moment, or the machine that runs Quill may be unable to reach +`slack.com`. + + + +**What to do:** wait a minute or two and try again. If the failure persists, verify that the machine that runs Quill can open HTTPS +connections to `slack.com`, as described in [Prerequisites](#prerequisites). + + + + + +##### The bot is already connected + +Clicking `Connect bot` fails with `Slack bot ... is already connected`. + + + +**Cause:** the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve +only one channel. When the channel is in another app, the message names that app. + + + +**What to do:** delete the channel that holds the bot, in this app or in the app the message names, as described in +[Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another bot from the manifest, with a name of its +own, as described in [Creating a Slack bot from Quill's manifest](#creating-a-slack-bot-from-quill-s-manifest), and paste the new +bot's credentials in this form instead. + + + + + +##### The bot's token is rejected + +The `Connect` tab shows `Token rejected`, and the bot does not answer. + + + +**Likely cause:** the bot's token may have been revoked on Slack, by **Revoke All OAuth Tokens** on its OAuth & Permissions page or by +uninstalling the bot from the workspace. +The users' messages still reach Quill, but the bot cannot post its replies, so the messages are not answered, and are not answered +later. Quill re-checks the token every few minutes, so the badge may turn red a few minutes after the revocation. The tab then +also shows the red alert "The bot couldn't deliver a reply" under the connection card, which remains until Quill is restarted. + + + +![The Connect tab with a rejected token](./assets/slack-bot_token-rejected.png) + +**What to do:** reinstall the bot from its OAuth & Permissions page on Slack, copy the new **Bot User OAuth Token** the page then +shows, and enter it in the channel, as described in [Rotating the credentials](#rotating-the-credentials). + + + + + +##### Quill rejects the messages Slack delivers -* **The `Request URL` field of the `Event Subscriptions` page shows "Your URL didn't respond."** - Likely cause: Slack may be unable to reach the deployment at the URL: Quill may be stopped, the machine that runs Quill may not - accept connections from the internet, or the URL may have been pasted incompletely. A channel that was deleted no longer answers - at its URL either. +The `Connect` tab shows a red alert, `A delivery failed signature verification`, under the connection card. - ![The Request URL field after a failed verification](./assets/slack-bot_url-not-responding.png) + - What to do: make sure that Quill is running, and that the machine that runs it accepts HTTPS connections from the internet, as - described in [Prerequisites](#prerequisites). Then paste the URL again from the channel's [Connect](#the-connect-tab) tab, and - click **Retry**. If the channel was deleted, add a channel for the bot again and paste the new channel's request URL instead. +**Likely cause:** the signing secret held by the channel may differ from the bot's: the secret may have been regenerated on Slack, +or mistyped when the channel was added. +Quill rejects the deliveries it cannot verify, so the users' messages are not answered until the secrets match. + + + +![The Connect tab with a failed signature verification](./assets/slack-bot_signature-failed.png) + +**What to do:** copy the **Signing Secret** from the **App Credentials** section of the bot's **Basic Information** page on Slack, and +enter it in the channel, as described in [Rotating the credentials](#rotating-the-credentials). The alert disappears once a +delivery is verified. +##### The bot receives no messages + +The `Connect` tab shows `Token valid`, but `Last message` does not change when users message the bot, and the bot does not answer. + + + +**Likely cause:** Slack may not be delivering the messages to Quill: the event subscription may be incomplete, the request URL may +have failed Slack's verification, or the deployment may no longer be reachable from the internet. + + + +**What to do:** open the bot's **Event Subscriptions** page on Slack and check that **Enable Events** is on, that the **Request URL** +is marked **Verified**, that `message.im` is listed under **Subscribe to bot events**, and that the changes were saved, as +described in [Finishing the event subscription on Slack](#finishing-the-event-subscription-on-slack). If the URL is not verified, +see the "Your URL didn't respond." entry below. + + + + + +##### The channel is paused + +The `Connect` tab opens with `This channel is paused, so the bot isn't answering right now.` + + + +**Cause:** the channel was paused, using **Pause** in the header of its details view. +Messages users send while the channel is paused do not reach the agent and are not answered later. + + + +**What to do:** resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + + +--- + +### In the bot's settings on Slack + + + +##### Slack cannot verify the Request URL + +The `Request URL` field of the `Event Subscriptions` page shows `Your URL didn't respond.` + + + +**Likely cause:** Slack may be unable to reach the deployment at the URL: Quill may be stopped, the machine that runs Quill may not +accept connections from the internet, or the URL may have been pasted incompletely. A channel that was deleted no longer answers +at its URL either. + + + +![The Request URL field after a failed verification](./assets/slack-bot_url-not-responding.png) + +**What to do:** make sure that Quill is running, and that the machine that runs it accepts HTTPS connections from the internet, as +described in [Prerequisites](#prerequisites). Then paste the URL again from the channel's [Connect](#the-connect-tab) tab, and +click **Retry**. If the channel was deleted, add a channel for the bot again and paste the new channel's request URL instead. + + + +--- + ### In the Slack client -* **A user cannot find the bot.** - Likely cause: the user may not be a member of the workspace the bot is installed in, or the bot may not be listed in the user's - sidebar. - What to do: if the user is not a member of the workspace, have a workspace admin invite the user. Then advise the user to search - for the bot's name in the Slack client's search box, and to write in the bot's **Messages** tab, as described in - [Starting a conversation](#starting-a-conversation). -* **The bot does not reply to a message posted in a Slack channel or in a group direct message.** - Likely cause: the bot reads only the direct messages sent to it. A message posted in a Slack channel, such as #general, or in a - group direct message with several people, does not reach the bot, even if the message mentions the bot. - What to do: advise the user to send the question in a direct message with the bot. -* **The bot replies "Sorry - something went wrong handling that message. Please try again."** - Likely cause: one of the following may have happened. - * The agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel was added. - * A parameter is bound to **Sender email**, and the Slack profile of the user who sent the message carries no email address. - * The agent failed to answer, e.g., because the database it queries or the LLM service it uses could not be reached. - - What to do: if a parameter is shown unbound in the channel's [Parameters](#the-parameters-tab) tab, bind it. If a parameter is - bound to **Sender email**, ask the user to check that the Slack profile shows an email address. If every parameter is bound, the - agent itself most likely failed to produce the answer: verify that the app's database, and the LLM service behind the agent's AI - connection string, can be reached. The connection string can be tested as described in - [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then send the bot a - question again. + + +##### A user cannot find the bot + + + +**Likely cause:** the user may not be a member of the workspace the bot is installed in, or the bot may not be listed in the user's +sidebar. + + + +**What to do:** if the user is not a member of the workspace, have a workspace admin invite the user. Then advise the user to search +for the bot's name in the Slack client's search box, and to write in the bot's **Messages** tab, as described in +[Starting a conversation](#starting-a-conversation). + + + + + +##### The bot does not reply in a channel or a group message + +The bot does not reply to a message posted in a Slack channel or in a group direct message. + + + +**Cause:** the bot reads only the direct messages sent to it. A message posted in a Slack channel, such as #general, or in a +group direct message with several people, does not reach the bot, even if the message mentions the bot. + + + +**What to do:** advise the user to send the question in a direct message with the bot. + + + + + +##### The bot reports that something went wrong + +The bot replies `Sorry - something went wrong handling that message. Please try again.` + + + +**Likely cause:** one of the following may have happened. + + + +* The agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel was added. +* A parameter is bound to **Sender email**, and the Slack profile of the user who sent the message carries no email address. +* A parameter is bound to a value the agent parameter's type no longer accepts, e.g., because the type was changed in the + agent after the channel was added. +* The agent failed to answer, e.g., because the database it queries or the LLM service it uses could not be reached. + +**What to do:** if a parameter is shown unbound in the channel's [Parameters](#the-parameters-tab) tab, bind it. If a parameter is +bound to **Sender email**, ask the user to check that the Slack profile shows an email address. If an agent parameter's type was +changed, bind the parameter again in the Parameters tab, with a value or a source that matches the type. If every parameter is +bound, the agent itself most likely failed to produce the answer: verify that the app's database, and the LLM service behind the +agent's AI connection string, can be reached. The connection string can be tested as described in [Dashboard: AI connection +strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then send the bot a question again. diff --git a/quill/channels/telegram-bot.mdx b/quill/channels/telegram-bot.mdx index 6b40412c7c..cd28b84428 100644 --- a/quill/channels/telegram-bot.mdx +++ b/quill/channels/telegram-bot.mdx @@ -214,8 +214,10 @@ A user can also start afresh at any moment by sending `/clear`. The bot confirms ![Clearing the conversation](./assets/telegram-bot_clear.png) In the chat above, the question answered before `/clear` can no longer be answered after it, since the list the question referred to -is no longer part of the conversation. -Clearing also deletes the conversation from the app's [Conversations view](../dashboard/manage-an-app/conversations-view.mdx) in the management dashboard. +is no longer part of the conversation. + +Clearing also deletes the current day's conversation from the app's [Conversations view](../dashboard/manage-an-app/conversations-view.mdx) in the management dashboard. +The conversations of earlier days remain in the view. @@ -476,90 +478,239 @@ The limits below follow this design and Telegram's own rules. None of them can b - - Symptoms met by the users of every bot type, not just of a Telegram bot, are listed in the channels overview, in [Troubleshooting](../channels/overview.mdx#troubleshooting). - - The symptoms below are shown by a Telegram bot channel when something goes wrong, each with its likely cause and what to do about it. The first symptoms are seen in Quill's management dashboard: in the channel form, in the **Edit channel** form, and in the Channels view. The rest are encountered by the bot's users in their chats with the bot on Telegram. The bot's messages are quoted in their default form, shown in [The Bot messages tab](#the-bot-messages-tab); a channel with customized messages shows your texts instead. - +--- ### In the dashboard -* **Clicking `Connect bot` fails with "invalid bot token format".** - Likely cause: the token pasted in the form may be incomplete or mistyped. A bot token is the bot's numeric id, a colon, and a - secret string, e.g., `123456789:AA...`. - What to do: copy the whole token from @BotFather's message, as described in - [Creating a bot using @BotFather](#creating-a-bot-using-botfather), and paste it in the form's - [Bot token](#filling-in-the-channel-form) field. -* **Clicking `Connect bot` fails with "telegram rejected the bot token".** - Likely cause: the token may have been replaced using @BotFather, so Telegram no longer accepts the old one. - What to do: paste the token @BotFather issued last in the form's [Bot token](#filling-in-the-channel-form) field; if you are not - sure which token is current, have @BotFather issue a new one and paste it. -* **Clicking `Connect bot` fails with "could not reach telegram" or "telegram did not respond".** - Likely cause: the machine running Quill may have no access to `api.telegram.org`, as required in [Prerequisites](#prerequisites); - a firewall or a proxy blocking the address is the usual cause. - What to do: allow outgoing HTTPS connections from the machine running Quill to `api.telegram.org` in the firewall or proxy that - blocks them, or ask your network administrator to. -* **Clicking `Connect bot` fails with "bot @... is already connected".** - Likely cause: the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve - only one channel. When the channel is in another app, the message names that app. - What to do: delete the channel that holds the bot, in this app or in the app the message names, as described in - [Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another bot using @BotFather, as described in - [Creating a bot using @BotFather](#creating-a-bot-using-botfather), and paste the new bot's token in this form instead. -* **Clicking `Save changes` in the `Edit channel` form fails with "the token belongs to a different bot".** - Likely cause: the new token may have been copied from @BotFather's message about a different bot. - What to do: paste the token of the bot the channel was added for in the **New bot token** field of the **Edit channel** form. - To switch to a different bot, add a new channel for that bot instead, as described in - [Connecting the bot to your app](#connecting-the-bot-to-your-app). -* **The channel shows as `Active` in the Channels view, but the bot does not answer.** - Likely cause: the bot token may have been replaced using @BotFather, so Telegram no longer answers the requests Quill makes - with the old one. - The dashboard shows no warning for a replaced token, and messages users send meanwhile are lost. - What to do: enter the token @BotFather issued last in the channel, as described in [Rotating the bot token](#rotating-the-bot-token). -* **The channel shows as `Disabled` in the Channels view, and the bot does not answer.** - Likely cause: the channel was paused, using **Pause** in the header of its details view. - Messages users send while the channel is paused are held by Telegram for up to 24 hours, and are answered if the channel is - resumed within this time. - What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + +##### The bot token's format is invalid + +Clicking `Connect bot` fails with `invalid bot token format`. + + + +**Likely cause:** the token pasted in the form may be incomplete or mistyped. A bot token is the bot's numeric id, a colon, and a +secret string, e.g., `123456789:AA...`. + + + +**What to do:** copy the whole token from @BotFather's message, as described in +[Creating a bot using @BotFather](#creating-a-bot-using-botfather), and paste it in the form's +[Bot token](#filling-in-the-channel-form) field. + + + + + +##### Telegram rejects the bot token + +Clicking `Connect bot` fails with `telegram rejected the bot token`. + + + +**Likely cause:** the token may have been replaced using @BotFather, so Telegram no longer accepts the old one. + + + +**What to do:** paste the token @BotFather issued last in the form's [Bot token](#filling-in-the-channel-form) field; if you are not +sure which token is current, have @BotFather issue a new one and paste it. + + + + + +##### Quill cannot reach Telegram + +Clicking `Connect bot` fails with `could not reach telegram` or `telegram did not respond`. + + + +**Likely cause:** the machine running Quill may have no access to `api.telegram.org`, as required in [Prerequisites](#prerequisites); +a firewall or a proxy blocking the address is the usual cause. + + + +**What to do:** allow outgoing HTTPS connections from the machine running Quill to `api.telegram.org` in the firewall or proxy that +blocks them, or ask your network administrator to. +##### The bot is already connected + +Clicking `Connect bot` fails with `bot @... is already connected`. + + + +**Cause:** the bot is already connected to another channel, in this app or in another app of the deployment; a bot can serve +only one channel. When the channel is in another app, the message names that app. + + + +**What to do:** delete the channel that holds the bot, in this app or in the app the message names, as described in +[Pausing and deleting the channel](#pausing-and-deleting-the-channel); or create another bot using @BotFather, as described in +[Creating a bot using @BotFather](#creating-a-bot-using-botfather), and paste the new bot's token in this form instead. + + + + + +##### The new token belongs to a different bot + +Clicking `Save changes` in the `Edit channel` form fails with `the token belongs to a different bot`. + + + +**Likely cause:** the new token may have been copied from @BotFather's message about a different bot. + + + +**What to do:** paste the token of the bot the channel was added for in the **New bot token** field of the **Edit channel** form. +To switch to a different bot, add a new channel for that bot instead, as described in +[Connecting the bot to your app](#connecting-the-bot-to-your-app). + + + + + +##### An active channel's bot does not answer + +The channel shows as `Active` in the Channels view, but the bot does not answer. + + + +**Likely cause:** the bot token may have been replaced using @BotFather, so Telegram no longer answers the requests Quill makes +with the old one. +The dashboard shows no warning for a replaced token, and messages users send meanwhile are lost. + + + +**What to do:** enter the token @BotFather issued last in the channel, as described in [Rotating the bot token](#rotating-the-bot-token). + + + + + +##### A disabled channel's bot does not answer + +The channel shows as `Disabled` in the Channels view, and the bot does not answer. + + + +**Cause:** the channel was paused, using **Pause** in the header of its details view. +Messages users send while the channel is paused are held by Telegram for up to 24 hours, and are answered if the channel is +resumed within this time. + + + +**What to do:** resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + + +--- + ### On Telegram -* **The bot replies "This assistant is not fully configured yet. Please contact whoever set up this bot."** - Likely cause: the agent may have a parameter the channel does not bind, e.g., a parameter added to the agent after the channel - was added. - What to do: bind the parameter in the channel's [Parameters](#the-parameters-tab) tab. -* **The bot replies "Sorry - something went wrong handling that message. Please try again."** - Likely cause: the agent failed to produce the answer, e.g., because the database it queries or the LLM service it uses could not - be reached. - What to do: verify that the app's database, and the LLM service behind the agent's AI connection string, can be reached. The - connection string can be tested as described in - [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then try the bot from - your own Telegram account. -* **The bot replies "This assistant needs your Telegram username. Set one in Telegram Settings and send your message again."** - Likely cause: a parameter is bound to **Telegram username**, and the user has no username set in Telegram. - What to do: advise the user to set a username in Telegram's settings and send the question again; or bind the parameter to - another source, in the channel's [Parameters](#the-parameters-tab) tab. -* **The bot replies "I only work in one-on-one chats. Message me directly to start a conversation." in a group, and then stays - silent there.** - Likely cause: the bot was added to a Telegram group; the bot answers in private chats only. - What to do: hand the users the bot's address, shown in the channel's [Connect](#the-connect-tab) tab, and advise them to open a - private chat with the bot at that address. -* **The bot asks a returning user for the phone number again.** - Likely cause: the channel may have been deleted and added again. The number is kept per channel, so a new channel has no record - of the number the user shared. - What to do: advise the user to share the number again. See [Returning users](#returning-users). + + +##### The bot reports that it is not fully configured + +The bot replies `This assistant is not fully configured yet. Please contact whoever set up this bot.` + + + +**Cause:** the agent has a parameter the channel does not bind, e.g., a parameter added to the agent after the channel +was added. + + + +**What to do:** bind the parameter in the channel's [Parameters](#the-parameters-tab) tab. + + + + + +##### The bot reports that something went wrong + +The bot replies `Sorry - something went wrong handling that message. Please try again.` + + + +**Likely cause:** one of the following may have happened. + + + +* A parameter is bound to a value the agent parameter's type no longer accepts, e.g., because the type was changed in the + agent after the channel was added. +* The agent failed to produce the answer, e.g., because the database it queries or the LLM service it uses could not be + reached. + +**What to do:** if an agent parameter's type was changed, bind the parameter again in the channel's [Parameters](#the-parameters-tab) +tab, with a value or a source that matches the type. Otherwise, verify that the app's database, and the LLM service behind the +agent's AI connection string, can be reached. The connection string can be tested as described in [Dashboard: AI connection +strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection). Then try the bot from your own Telegram account. + + + + + +##### The bot asks for a Telegram username + +The bot replies `This assistant needs your Telegram username. Set one in Telegram Settings and send your message again.` + + + +**Cause:** a parameter is bound to **Telegram username**, and the user has no username set in Telegram. + + + +**What to do:** advise the user to set a username in Telegram's settings and send the question again; or bind the parameter to +another source, in the channel's [Parameters](#the-parameters-tab) tab. + + + + + +##### The bot does not answer in a group + +The bot replies `I only work in one-on-one chats. Message me directly to start a conversation.` in a group, and then stays silent there. + + + +**Cause:** the bot was added to a Telegram group; the bot answers in private chats only. + + + +**What to do:** hand the users the bot's address, shown in the channel's [Connect](#the-connect-tab) tab, and advise them to open a +private chat with the bot at that address. + + + + + +##### The bot asks for the phone number again + +The bot asks a returning user for the phone number again. + + + +**Likely cause:** the channel may have been deleted and added again. The number is kept per channel, so a new channel has no record +of the number the user shared. + + + +**What to do:** advise the user to share the number again. See [Returning users](#returning-users). diff --git a/quill/channels/web-widget.mdx b/quill/channels/web-widget.mdx index 662d8a0f7d..9e2fdaf17d 100644 --- a/quill/channels/web-widget.mdx +++ b/quill/channels/web-widget.mdx @@ -697,68 +697,185 @@ The **Customize appearance** tab holds the chat box's theme: its colors, style, - - Symptoms met by the users of every channel type are listed in the channels overview, in [Troubleshooting](../channels/overview.mdx#troubleshooting). +The symptoms below are shown by a web widget channel when something goes wrong, each with its likely cause and what to do about it. + +--- + +### In the dashboard + + + +##### An allowed origin is refused + +Creating or saving the channel fails with `is not an origin (scheme+host[:port] only)`. + + + +**Cause:** an **Allowed origins** entry carries more than the website's address, +e.g., a page path (`https://shop.example.com/help`). + -The symptoms below are shown by a web widget channel when something goes wrong, each with its likely cause and what to do about it. +**What to do:** enter the website's address only (`https://shop.example.com`), as described in +[Filling in the channel form](#filling-in-the-channel-form). + + -### In the dashboard +##### The `*` wildcard is refused -* **Creating or saving the channel fails with "is not an origin (scheme+host[:port] only)".** - Likely cause: an **Allowed origins** entry carries more than the website's address, - e.g., a page path (`https://shop.example.com/help`). - What to do: enter the website's address only (`https://shop.example.com`), as described in - [Filling in the channel form](#filling-in-the-channel-form). -* **Creating or saving the channel fails with "wildcard '*' is not an allowed origin".** - Likely cause: `*` was entered in **Allowed origins** to permit every website. - What to do: leave the list empty to permit every website, or list each website by its address. -* **The `New web widget channel` form shows "Create an agent first" instead of its fields.** - Likely cause: the app has no agent yet. - What to do: add an agent, as described in [Prerequisites](#prerequisites), and then add the channel. -* **The `Generate link` button is disabled.** - Likely cause: the channel is paused. - What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). +Creating or saving the channel fails with `wildcard '*' is not an allowed origin`. + + + +**Cause:** `*` was entered in **Allowed origins** to permit every website. + + + +**What to do:** leave the list empty to permit every website, or list each website by its address. +##### The channel form asks to create an agent first + +The `New web widget channel` form shows `Create an agent first` instead of its fields. + + + +**Cause:** the app has no agent yet. + + + +**What to do:** add an agent, as described in [Prerequisites](#prerequisites), and then add the channel. + + + + + +##### The `Generate link` button is disabled + + + +**Cause:** the channel is paused. + + + +**What to do:** resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel). + + + +--- + ### On your website page -* **The chat box does not appear: the `