---
title: "Troubleshooting"
description: "Each failure with a known cause, its fix, and where the full answer lives."
---

> Documentation Index
> Fetch the complete documentation index at: https://commentware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

import CopyText from "../../components/CopyText.astro";

The failures with a known cause, by the symptom you see: the extension on a
page, connecting to a server, the server itself, notifications, dictation, and
links to a comment.

## Nothing happens on a page

The extension is not running on this page. Most likely first: it was installed
after the tab was opened, it is not installed in this browser, Chrome has
switched it off, or the page is one no extension runs on.

1. Open [/ext/](/ext/). It says whether the extension is running in this browser.
2. If you installed it a moment ago, reload the page. An extension does not
   reach a tab that was already open.
3. If /ext/ says Commentware is not running on this page, open /ext/ at the
   address it names. If it says the same there, install the extension. See
   [Install the Chrome extension](/docs/install/).
4. If you loaded it unpacked, open `chrome://extensions` and
   turn developer mode back on. Chrome switches unpacked extensions off when
   developer mode is off.

`chrome://` pages, the Chrome Web Store and Chrome's built-in PDF viewer never
run an extension, so nothing fixes them.

To check that it worked, press the keyboard shortcut on the page. The comment
overlay opens.

## The keyboard shortcut does nothing

Chrome owns the binding, another extension may have taken it, and it can be
cleared without anything saying so.

1. Open `chrome://extensions/shortcuts` and find Commentware.
2. Set the shortcut, or remove it from the extension that holds it.

The side panel needs no shortcut: click the toolbar icon.

To check that it worked, press the shortcut on a page. The comment overlay
opens.

## Comments are drawn but cannot be clicked

A dialog or a fullscreen element on the page has taken every click for itself,
or something is drawn over the overlay's toolbar. Learn more about [dialogs that
block the page](/docs/concepts/dialogs/).

1. Press the keyboard shortcut to take the page back. See [Use comments over a
   dialog](/docs/using/modes/).
2. If the overlay says it is **covered** rather than blocked, scroll, or drag
   the toolbar somewhere clearer.

To check that it worked, click a pin. Its thread opens.

## A control is disabled and says the server cannot do it

The extension and the server are released separately, and one of them is older
than the other. The control names the side to update. Learn more about [how the
extension and a server agree](/docs/concepts/versions/).

1. Hover the control and read which side it names.
2. If it names the server, follow [Update the server](/docs/server/#update-the-server)
   for the way you installed it.
3. If it names the extension, follow [Update Commentware](/update-extension/). Running
   the install command again is the update.

To check that it worked, open the page again. The control is enabled. After a
server update this can take up to five minutes, because the extension reuses
what the server said it speaks for up to five minutes before asking again.

## Opening a connection string does nothing

The browser has not stored the connection. Most likely first: it is waiting for
you to confirm, it is already waiting on another one, or the address names a
machine the browser cannot reach.

1. Look for the page asking you to confirm, and press its button. Nothing is
   stored before you do.
2. If no window appears at all, open the link again in a new tab. Commentware
   is already waiting on another connection, or that tab has already asked once.
3. If the string names `127.0.0.1` and the server runs on another machine,
   mint a string with the address your browser reaches it on. `127.0.0.1`
   means the browser's own machine. See [An address your browser can
   reach](/docs/connect/#an-address-your-browser-can-reach).
4. If it still does nothing, add the server by its address alone on the options
   page. That needs no key, and it says whether anything answers there.

To check that it worked, open the options page. The server is listed.

## A Commentware server is already using this database

Another server has the same database open. Two servers on one SQLite file
overwrite each other's writes, so the second one refuses to start. The refusal
names the process, the address it is listening on, and the database:

```text
A Commentware server is already using this database (pid 790428, listening on 127.0.0.1:7100).
  database: /home/alex/review/.tmp/comments/data.db
```

The same refusal about a blob directory reads "already using this blob
directory".

1. If you meant to use the server that is running, use it. Every command
   reaches it without a second start.
2. If you meant a second server, point this one somewhere else: with `db` in its
   [`commentware.config.json`](/docs/server/config/), or with `blobs` when the
   refusal names the blob directory.
3. If the other server should not be running, stop it from a directory whose
   config file names it:

```sh
commentware stop
```

4. If the refusal ends "If that process is long gone", and no process with that
   pid is running, delete the lock file it names.

See [Run one server per database](/docs/server/#one-server-per-database).

To check that it worked, run `commentware where`. It names the database you
meant and, when a server is running against it, that server.

## There is no Commentware database at this path

The command was pointed at a database that does not exist, most often by a
`commentware.config.json` in a directory above you. Only `commentware start`
creates a database; every other command refuses. The refusal says which file
named the path:

```text
There is no Commentware database at this path.
  database: /home/alex/review/.tmp/comments/data.db
  named by: /home/alex/review/commentware.config.json
```

1. Run `commentware where`. It prints the database and the file that named it,
   without opening or creating anything.
2. If that is the server you meant, start it with `commentware start`.
3. If it is not, run the command from the directory you meant, or pass
   `--config` with the path to that directory's config file.

To check that it worked, run the command again. It answers instead of refusing.

## A comment's pin is in the wrong place

The page changed under the comment, and the pin found a different element or
none. Learn more about [how a pin finds its element](/docs/concepts/threads-and-pins/).

1. Open the thread and read the line that says how well it found the element.
2. Drag the pin onto the thing the comment is about. It re-anchors from
   scratch. See [Move a pin and edit its screenshot](/docs/using/pins/).

The options page's **Sites** screen lists a site's pages most drifted first.

To check that it worked, reload the page. The pin is on the element you dropped
it on.

## A comment has no screenshot

The composer says which of four things happened: screenshots are switched off
for this site or the whole server, Chrome will not photograph this tab, the file
was too large, or the server declined its format. Posting never waits for a
screenshot. See [When there is no
screenshot](/docs/using/pins/#when-there-is-no-screenshot).

1. If screenshots are switched off, turn them on. See
   [Settings](/docs/server/settings/#screenshots).
2. On the thread card, select **Retake**. It takes the screenshot now.

Some pages cannot be captured at all, and no step fixes them.

To check that it worked, look at the thread card. It shows the screenshot.

## No notifications

Most likely first: your operating system dropped the cards, the bell is off, or
Chrome's permission for the extension is off.

1. Open the options page's **Notifications** screen. It holds the last 50 you
   were sent.
2. If they are there, they were delivered and your machine dropped the cards.
   Turn off focus mode, or allow Chrome to notify in your operating system's
   settings.
3. If the bell is off, turn it on, on the comment overlay's toolbar or on the
   extension's **Settings** screen.
4. If Chrome's own notification permission for the extension is off, turn it
   on. With it off nothing is shown, and nothing is marked delivered either, so
   everything waits for you.

See [Read and silence notifications](/docs/using/notifications/).

To check that it worked, wait for the next notification. Notifications arrive
on a 60-second check, so a card appears within a minute of a reply.

## No count on the extension's icon

The count only appears on sites your server already holds comments for, so that
your browsing is not reported page by page. A site that gained its first
comment somewhere else can go up to half an hour without one. Resolved threads
are not counted. Learn more about [the counter on the
icon](/docs/concepts/notifications/#the-counter-on-the-icon).

1. Leave a comment on the site.

To check that it worked, look at the icon on a page of that site with an
unresolved thread. It shows the count.

## The microphone button opens the setup instead of dictating

Dictation is not set up yet. Hovering the button names what is missing in place
of "Dictate this comment": "Allow Commentware to use your microphone", "Choose
where your speech is recognized", or "Download the voice model to dictate on
this computer".

1. Press the microphone button. The setup opens at the step that is missing.
2. Finish the setup.

**Manage dictation settings** on the extension's **Settings** screen opens the
same setup. See [Dictate a comment](/docs/using/dictation/).

To check that it worked, hover the button. It reads "Dictate this comment".

## Open this comment with Commentware

Nothing took the link over, and the page cannot tell why. Most likely first:
the extension is not installed in this browser. Or the link is on this site,
but at an address the extension does not open links at. Or the link is on a
server's own address, and this browser holds no connection to that server. A
link to a document reads "Open this document with Commentware", and the steps
are the same.

1. If Commentware is not installed, install it. See [Install the Chrome
   extension](/docs/install/).
2. If Commentware is installed and the link is on this site, replace the start
   of the link, up to the first single `/`, with the address Commentware opens
   links at. A comment's page names it, and so does [/ext/](/ext/). Then open
   it. `localhost:6900` and `127.0.0.1:6900` are different addresses
   to Commentware, so the address must match exactly.
3. If the link is on a server's own address, paste that server's connection
   string on the options page. See [Connect to a server](/docs/connect/).

To check that it worked, open the link again. The comment's page opens with the
thread.

## A permalink says this browser is not connected to its server

A permalink on this site's address names a server this browser holds no
connection to. The page reads "This browser is not connected to", then the
server, and never shows you a thread from a different server.

1. Paste that server's connection string on the options page. See [Connect to a
   server](/docs/connect/).

To check that it worked, open the link again. The comment's page opens with the
thread.

## A permalink says it is for another server

The page reads "This link is for a comment on" another server. A link on a
server's own address opens only that server's comments, because a page on one
server's address has no business spending your key on another.

1. Open the link on the address it names.

A link an agent built on this site's address has no such limit: this site
answers for whichever server the link carries.

To check that it worked, open the link on that address. The comment's page
opens with the thread.

## Comments landed in the wrong project

This browser, or the agent that wrote them, is in a different
[project](/docs/concepts/projects-and-sites/) from the one you meant. Your
browser's project is its own, and an agent chooses its own separately.

1. Hover the project mark, a colored circle with the project's first letter, in
   the side panel's header or on the page's toolbar. It names the project.
2. If it is not the one you meant, select the mark and choose the project.
3. If the site's existing comments should move too, open the options page's
   **Projects** screen and move the site.
4. If an agent wrote them, have it call `set_active_project`.

To check that it worked, hover the mark. It names the project you chose.

## The connection string scrolled away

Keys are stored hashed, so nothing can print the string again. Mint the same
user another key instead.

1. Find the user's id:

```sh
commentware users list
```

2. Mint a key for that id:

```sh
commentware users generate <id>
```

   It prints a new connection string, and every key the user already held goes
   on working.

See [give a user another key](/docs/server/users/#a-second-key-and-a-lost-one).

To check that it worked, paste the new string on the options page. The server
is listed.