Skip to main content

Quill: Troubleshooting

Starting Quill​

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.
The symptoms below may appear while Quill starts, or keep Quill from starting.
In the commands below, quill-<name> is the name the sign-up Docker command gives the container, where <name> 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-<name> with your container's name instead of quill-<name>, and run the Docker command you copied at sign-up again.

The license key is not set​

The terminal prints the error: 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-<name> with your container's name instead of quill-<name>, 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.
Then remove the container using docker rm -f quill-<name> with your container's name instead of quill-<name>, 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:

  1. Read web.log to find the error that stopped the activation, using the command shown in Starting Quill: When Quill does not come up.
  2. Correct the problem the error names.
  3. Restart the container using docker restart quill-<name>, with your container's name instead of quill-<name>.
    Quill attempts the activation once each time it starts, so it does not retry a failed activation until the container restarts.
Quill is not ready after 180 seconds​

The terminal prints the error: 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-<name>.
    The command prints nothing if the connection succeeds, and an error if it fails.

    docker exec quill-<name> 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, 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.

  • 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.<name>.myquill.ai, with your deployment name instead of <name>, 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.

The RavenDB server is not reachable​

The terminal prints Status: FAILED with Reason: ravendb is not reachable:, followed by an error message.

Cause: while starting, Quill's web application could not complete its first requests to the RavenDB server inside Quill's container: the server did not answer within 30 seconds of the attempt, or answered with an error.

What to do:

  1. Wait for Quill's next attempt.
    After a failed attempt, the web application tries again 15 seconds later, and keeps trying until the RavenDB server answers. The terminal then prints Status: READY.

  2. If the terminal does not print Status: READY, read the web application's log, in which each failed attempt is recorded with its error, using the command below with your container's name instead of quill-<name>.

    docker exec quill-<name> sh -c "tail -40 /var/lib/quill/logs/web.log"

  3. To find the reason the RavenDB server does not answer, read the server's logs, using the commands shown in Quill is running, but is not serving requests.

Quill is running, but is 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: read the web application's log, in which its failed attempts to reach the RavenDB server are recorded with their error (e.g., Connection refused when the RavenDB server is not running), using the command below with your container's name instead of quill-<name>.

docker exec quill-<name> sh -c "tail -40 /var/lib/quill/logs/web.log"

To find the reason the RavenDB server does not answer, read the server's logs using the commands below:

  • The server's own log file, in which the server records its errors, including the reason it failed to start, if it did.

    docker exec quill-<name> sh -c "tail -40 /var/lib/quill/logs/ravendb-server/server.log"

  • The server process's console output, including the full error when the server fails to start.
    The terminal names this file when the RavenDB server stops: it prints ERROR: ravendb is down or ERROR: ravendb stopped unexpectedly and was restarted, followed by Details: /var/lib/quill/logs/ravendb.log.

    docker exec quill-<name> sh -c "tail -40 /var/lib/quill/logs/ravendb.log"
The terminal reports that a Quill service is down​

The terminal prints ERROR: <service> is down or ERROR: <service> stopped unexpectedly and was restarted, followed by Details: and the service's log file.

Cause: one of the services inside Quill's container stopped. Quill starts a stopped service again, and the terminal then prints <service> is back up.

The effect depends on the service that stopped:

  • web, Quill's web application
    While web is down, the management dashboard and the channels do not answer, and the terminal prints no status.
  • proxy, nginx, which receives every connection to Quill
    While proxy is down, nothing outside Quill's container reaches Quill, although the terminal may still show Status: READY.
  • certwatch, which reloads nginx when Quill's certificate is renewed
    While certwatch is down, the dashboard answers as usual.

For ravendb, see Quill is running, but is not serving requests.

What to do:

  1. Wait for the terminal to print <service> is back up. For web, also wait for Status: READY.

  2. If the service stays down or keeps stopping, read the log file named in the Details: line (e.g., when nginx cannot start, proxy.log records the reason), using the command below with the service's name instead of <service> and your container's name instead of quill-<name>.

    docker exec quill-<name> sh -c "tail -40 /var/lib/quill/logs/<service>.log"

  3. If the log names a cause that another entry on this page describes, follow that entry. Otherwise, contact support and include the log lines you found.

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.

Signing in to the management dashboard​

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.
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 the message: That API key wasn't accepted. Double-check it and try again.

Likely cause: one of the following may have happened.

Signing in is refused for a moment​

Signing in fails with the message: We couldn't sign you in. Please try again in a moment.

Likely cause: one of the following may have happened.

  • More than 10 sign-in attempts were made from your IP address within a minute.
    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.
  • The sign-in request did not reach Quill's web application, which serves the management dashboard (e.g., because the web application was restarting, or the browser lost its connection to Quill).
    What to do: sign in again in a moment. If the message remains, check the symptoms listed in Starting Quill.
The dashboard API key is lost​

What to do: try the following, in this order:

  1. Find the key in the Docker command the container was started with.
  2. If the container still uses the key issued at sign-up, find the key in the email sent at sign-up, or sign up again 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.
  3. 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.

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.
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 and still started with this key accepts it: replace the key in each of these deployments, as described in Operator Authentication: 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 4 to 8 hours after anyone last used the management dashboard in this browser, as explained in Operator Authentication: Restarting the container is not enough.
    This browser stays signed in while one of its tabs shows a dashboard view that refreshes itself (e.g., an app's Overview), even if nobody uses the dashboard.
Signing in with the old API key still works​

Signing in with the old dashboard API key still works 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.

Connecting the source database​

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.
The symptoms below may appear in these two stages.

The connection test fails​

Clicking the Test connection button in the Connect to your source database stage of the Add new app wizard 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.
  • 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.
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.

The selected tables are refused​

Clicking the Verify schema button or the Next button in the Verify your schema stage of the Add new app wizard 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: do one of the following:

  • Grant this database user the permission the error names.
  • Have a database administrator run the statement the error carries.
    The statement may be in the error's details: click Show details under the message to see them.
    On PostgreSQL, grant the permission instead when the statement creates the publication or the replication slot: Quill looks for these objects under names of its own, so a publication or slot created by an administrator is not used.

The permissions each database type requires are listed in Connecting your database: 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.

    On MySQL and MariaDB, the side panel has no effect: Quill lists only the tables of the database named in the Database field of the Connect to your source database stage.

  • 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.
To list only the tables that have warnings, select Warnings in the filter beside the Search by table name... box.

Cause: the table has no primary key, or its replica identity is set to NOTHING. The warning names the condition, and carries a statement that sets the table's replica identity to FULL.

What to do, by the warning:

  • Table '…': the table has no primary key and REPLICA IDENTITY is DEFAULT, …
    Quill cannot mirror a table without a primary key. When you click the Verify schema button or the Next button in the Verify your schema stage of the Add new app wizard, Quill refuses the table with the message: Table '…' has no primary key, so CDC cannot derive stable document ids for it.
    Running the statement the warning carries removes the warning, but Quill still refuses the table.
    Have a database administrator add a primary key to the table, or leave the table unselected.

  • Table '…': REPLICA IDENTITY is set to NOTHING, …
    PostgreSQL has no columns with which to identify the row an update or a deletion changed.
    Before creating the app, have a database administrator run the statement the warning carries (e.g., ALTER TABLE <schema>.<table> REPLICA IDENTITY FULL;), or leave the table unselected, as described in Connecting your database: Choosing the tables.
    If the app is already created, running the statement lets the table's updates and deletions succeed again.

    Once the app is created, Quill adds the table to a publication, the list of tables whose changes PostgreSQL streams to Quill. If the table's replica identity is still NOTHING, PostgreSQL then 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.

SQL Server Agent is not running​

The Verify your schema stage shows the warning: 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.

Mapping the source tables​

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.
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.

The Raw JSON toggle cannot be switched off​

Switching the Raw JSON toggle off in the Map schema stage of the Add new app wizard is refused with a message that names a problem related to JSON, e.g.: The raw configuration is not valid 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.

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.

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.

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.

AI connection strings​

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.
  • 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.
  • 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.
No models are suggested​

The Model field suggests no models, 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.

  • 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).
    What to do: click the side panel's Test connection button to see the reason the provider gave, and fix the problem it names (e.g., enter the full API key again).

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.

Agents answer differently after a connection string is added​

Agents that were set up before a new connection string was added in the AI connection strings view now answer differently.

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 and task 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.

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: When the connection string is in use.

Deleting a connection string fails with a list of its uses​

In the AI connection strings view, clicking a connection string's delete icon and then Delete in the Delete connection string? dialog does not delete the connection string.
Instead, the dialog shows This connection string is still in use. Remove what uses it first:, followed by a list of the agents and tasks that use the connection string.

Cause: an agent or a task started using the connection string after the management dashboard last loaded the list of connection strings (e.g., you set an agent to use the connection string in another browser tab). The view's Used by column therefore still showed Not used, and the delete icon was available. Quill refuses to delete a connection string that is in use.

What to do:

  1. Switch each agent or task that the dialog lists to another connection string, or delete the agent or task, as described in AI Connection Strings View: When the connection string is in use.
  2. Reload the AI connection strings view in your browser. When the connection string's row shows Not used in the Used by column, delete the connection string.

Agents​

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 of the Add agent wizard cannot be selected.

Likely cause: one of the following may have happened.

  • The Terms of Use of the RavenDB AI service were not accepted yet. The stage then shows a Review the Terms of Use button.
    What to do: click the 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.
  • Quill could not check whether the terms were accepted. Quill runs this check through the RavenDB server inside Quill's container, which asks the RavenDB service at api.ravendb.net. The check fails when the RavenDB service cannot be reached, or answers with an unexpected response. The stage then shows the message Could not check whether the AI service is available. and a Try again button.
    What to do: make sure Quill's machine allows outgoing HTTPS connections to api.ravendb.net, and click the Try again button. Until the check succeeds, you can set the agent up using the Setup manually option.
No agents are suggested​

In the Create your Agent with AI stage of the Add agent wizard, the AI-suggested agents based on your data section shows the message AI could not suggest agents from your data. Describe your own below, or set one up manually. instead of suggestion cards.

Likely cause: Quill could not get suggested agents from the RavenDB AI service (e.g., because the service could not be reached from Quill's machine, did not answer within the time Quill allows the request, five minutes by default, or returned no usable suggestion).

What to do:

  1. Make sure Quill's machine allows outgoing HTTPS connections to api.ravendb.net.
    To check whether Quill's container can reach api.ravendb.net, use the command shown in Quill is not ready after 180 seconds.
  2. Have Quill request the suggested agents again: click Back, and then Next.

Until the suggestions arrive, you can set the agent up using the Setup manually option, as described in Adding an AI agent: Choosing a starting point.

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.

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.

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 the message: 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 a required parameter of the tool. 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-<name>. It prints the reason Quill logged, which names the query tool and the placeholder.

docker exec quill-<name> grep -E "contains parameters that are not defined|is defined on both the agent level" /var/lib/quill/logs/web.log

If the command prints nothing, Quill refused the configuration for another reason (e.g., a query tool's query that is not a read query), or the test failed for another reason (e.g., an error returned by the LLM provider).
To print the reasons Quill logged for the latest refusals and failed tests, run the command below, with your container's name instead of quill-<name>. Each reason follows the last | of its line (e.g., Expected end of query but got: update).

docker exec quill-<name> sh -c "grep -E 'Agent (edit|provisioning) rejected by RavenDB|setup/try failed' /var/lib/quill/logs/web.log | tail -3"

What to do, by the reason the commands print:

  • 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 to its Parameters JSON schema with the name listed under the schema's required field, 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 a required parameter of the query tool define the placeholder.
    Remove one of the two.
  • Any other reason
    Correct the part of the configuration the reason names (e.g., remove the update clause from the query tool's query).

Both sources are described in Agents View: 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.
The conversation's transcript is described in Conversations View: 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 65536 bytes, as described in Agents View: Agent actions.
The conversation's transcript is described in Conversations View: The conversation's transcript.

Mirroring​

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.
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 Channels Overview: The agent answers from outdated information.

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.

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.

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.
The list is cleared when you change the app's settings and save them in the Edit app wizard. Restarting the sync does not clear it.

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.

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:

  1. 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.
  2. Click the Restart sync option of the same menu again, as described in Data Source View: 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.

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.

Channels​

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:

Network and DNS​

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 DNS & IP Configuration: The published hostnames.
Each hostname ends with your deployment name and myquill.ai, e.g., dashboard.<name>.myquill.ai, where <name> 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 DNS & IP Configuration: What remains unchanged.

  2. Run the command below on Quill's machine, with your container's name instead of quill-<name> and the machine's new IP address instead of <new-ip>:

    docker exec quill-<name> update-dns --ip <new-ip>

    When the DNS service completes the update, which may take up to 15 minutes, update-dns prints the message: Successfully registered DNS record(s) for '<name>.myquill.ai' in api.ravendb.net.

Updating the records is described in DNS & IP Configuration: 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 My apps at the top of the management dashboard's sidebar, and then click IP configuration under Settings.

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:

  1. Look up Quill's hostnames, using the commands described in DNS & IP Configuration: Verify the change, and check the 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.
  2. If the lookups still show the old address 30 minutes after the update-dns command timed out, 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 DNS & IP Configuration: 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 DNS & IP Configuration: 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, fails with a certificate error, or fails only from other devices on your network.

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.

  • Other devices on your network cannot connect, while the Windows machine running Quill reaches it through localhost: if Quill runs in WSL 2 (e.g., on Docker Desktop for Windows), WSL's default networking mode or a firewall may prevent LAN traffic from reaching Quill.

    What to do:
    Enable WSL mirrored networking with hostAddressLoopback, point Quill's hostnames at the Windows machine's LAN address, and verify access from another device, as described in LAN Access on Windows.

  • 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-<name>, with your container's name instead of quill-<name>.

    • 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.
      2. Remove the container using docker rm -f quill-<name>, with your container's name instead of quill-<name>.
      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.<name>.myquill.ai). The certificate covers only hostnames ending with .<name>.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-<name>:

      docker exec quill-<name> 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 DNS & IP Configuration: 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.<name>.myquill.ai.

Cause: external applications connect through db.<name>.myquill.ai to the RavenDB server inside Quill's container, which holds the apps' databases, as described in Network Architecture: 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.

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.<name>.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-<name> with your container's name instead of quill-<name>.

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.

Updates and expiry​

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 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.
The symptoms below may appear when a build expires, while you update Quill, when Quill's license expires, or when Quill cannot reach the license server.

The build has expired​

Instead of the management dashboard, the browser shows a notice titled Quill needs updating, with the message: 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.
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.

The build is still expired after an update​

After you updated Quill, the browser still shows a notice titled 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.
  3. Remove the replacement container using docker stop quill-<name> and docker rm quill-<name>, with your container's name instead of quill-<name>.
  4. Run the changed command.

Refreshing the image is described in Updating Quill: 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.
  2. Remove the existing container using docker stop quill-<name> and docker rm quill-<name>, with your container's name instead of quill-<name>.
  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.

The license has expired​

The License view shows the message: This license has expired.

Cause: the expiration date of Quill's license, shown in the view, has passed.

What to do: to renew the license, contact RavenDB sales.
Updating Quill does not renew the license.
To open the view, click My apps at the top of the management dashboard's sidebar, and then click License under License & usage. The view is described in License View: Current license.

The dashboard shows no WRU figures​

The WRU card of the My apps view and of an app's Overview shows — with the caption Unavailable from the license server, and the My apps table shows — in its WRU / month column.
The Usage view shows Could not load usage and Could not load per-app usage instead of the WRU chart and the Usage per app table.

Likely cause: the RavenDB server inside Quill's container cannot reach the RavenDB service at api.ravendb.net, from which the RavenDB server gets the WRU figures.
Quill reads the figures of the other cards (Conversations, Prompts, and Tokens) from the apps' databases, so these cards still show their figures.

To confirm this cause, click My apps at the top of the management dashboard's sidebar, and then click License under License & usage to open the License view.
The cause is confirmed if Connectivity, in the view's License health section, shows a status other than OK next to a red dot. If the connection failed, the error message appears below the status, as described in License View: Connectivity.

What to do:

  1. Make sure Quill's machine allows outgoing HTTPS connections to api.ravendb.net.
    To check whether Quill's container can reach api.ravendb.net, use the command shown in Quill is not ready after 180 seconds.
  2. Click Refresh in the License view to run the check again. Once Connectivity shows OK, click Retry in the Usage view, and reload the My apps view or the app's Overview in your browser.
  3. If Connectivity shows OK and the WRU figures are still unavailable, contact support.

Contacting support​

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 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-<name>:

docker exec quill-<name> 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-<name>.

  • The symptom
    What you did, what you expected to happen, and the exact message Quill showed or printed.

  • The Quill image the container runs

    docker inspect quill-<name> --format "{{.Config.Image}}"

  • The messages Quill printed while starting and running

    docker logs --tail 100 quill-<name>

  • 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.

    docker exec quill-<name> curl --silent http://127.0.0.1:5000/api/bootstrap/status

  • Quill's recent application messages

    docker exec quill-<name> 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, 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.

In this article