Troubleshooting — Commentware

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.

Open /ext/. It says whether the extension is running in this browser.
If you installed it a moment ago, reload the page. An extension does not reach a tab that was already open.
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.
If you loaded it unpacked, open 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.

Open and find Commentware.
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.

Press the keyboard shortcut to take the page back. See Use comments over a dialog.
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.

Hover the control and read which side it names.
If it names the server, follow Update the server for the way you installed it.
If it names the extension, follow Update Commentware. 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.

Look for the page asking you to confirm, and press its button. Nothing is stored before you do.
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.
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.
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:

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

If you meant to use the server that is running, use it. Every command reaches it without a second start.
If you meant a second server, point this one somewhere else: with db in its commentware.config.json, or with blobs when the refusal names the blob directory.
If the other server should not be running, stop it from a directory whose config file names it:
```
commentware stop
```
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.

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:

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

Run commentware where. It prints the database and the file that named it, without opening or creating anything.
If that is the server you meant, start it with commentware start.
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.

Open the thread and read the line that says how well it found the element.
Drag the pin onto the thing the comment is about. It re-anchors from scratch. See Move a pin and edit its screenshot.

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.

If screenshots are switched off, turn them on. See Settings.
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.

Open the options page’s Notifications screen. It holds the last 50 you were sent.
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.
If the bell is off, turn it on, on the comment overlay’s toolbar or on the extension’s Settings screen.
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.

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.

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

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

Manage dictation settings on the extension’s Settings screen opens the same setup. See Dictate a comment.

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.

If Commentware is not installed, install it. See Install the Chrome extension.
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/. Then open it. localhost:6900 and 127.0.0.1:6900 are different addresses to Commentware, so the address must match exactly.
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.

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.

Paste that server’s connection string on the options page. See Connect to a server.

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.

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 from the one you meant. Your browser’s project is its own, and an agent chooses its own separately.

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.
If it is not the one you meant, select the mark and choose the project.
If the site’s existing comments should move too, open the options page’s Projects screen and move the site.
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.

Find the user’s id:
```
commentware users list
```
Mint a key for that id:
```
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.

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