Troubleshooting

Troubleshooting

The sentence at the top of the settings page

The settings page opens with one sentence about what the plugin is actually doing, as against what it was told to do. Three situations, and they are not the same fault.

"This plugin is not storing anything. Its store could not be opened (...), so plays are being lost for as long as that lasts. The server log carries the failure itself."

The store could not be opened. This is the broken one and it is losing plays. The named failure is the one the plugin met, and the server log carries it in full.

The common cause on release 0.1.0.0 is a 10.11 server older than the first patch shipping Microsoft.Data.Sqlite 9.0.11: that build binds a version those servers do not carry, so it loads, reports itself active, and then cannot open its store. The server log shows the plugin loaded and then an error naming a FileNotFoundException, and no plays.db appears in the plugin's data folder. The repair is in the next release, and until then the answer is a newer 10.11 server. Support matrix and releases has the detail.

"Recording is switched off, so nothing new is being written."

Somebody's decision, not a fault. Capture is off in the settings on the same page. What is already stored is untouched.

"Recording."

Working. It is followed either by when the oldest play still held started, or by "Nothing is stored yet.", which means the store opened and holds no play. That date is rendered by the browser in the reader's own zone; the zone this plugin folds days under is a setting on the same page and a different question.

Reading the empty date without reading the failure first would tell somebody whose store is broken that their server has never played anything, which is why the failure is stated first.

A save that was refused

"Nothing was saved. One of the values entered is outside what this plugin accepts, and a save is refused whole rather than in part, so none of the other changes were written either. The values shown are the ones in force."

A save is refused whole. Nothing on the page was written, including the fields that were fine. The range each field takes is written under that field on the page, and the server log names the field that was refused:

A save was refused. The value sent for {Fields} is outside what this plugin
accepts, so nothing was written and the stored settings are unchanged.

Correct the field the log names and save again.

Stored settings that fell back to a default

"The stored value of ... was outside what this plugin accepts, so the default is being used instead. Saving this page writes the values shown here."

This appears above the form when the settings file already held a value the running build refuses, which is what an upgrade or a hand-edited file can leave behind. The named fields are running on their defaults. Saving the page writes the values shown, which ends the state.

The lines this plugin writes to the server log

Nothing is written on the ordinary path. A play that starts, reports progress and stops writes no line at all, at any level. Every line below is a fault or a migration, and none of them carries a user name or an item title.

line	level	what it means
The plays a previous run left open could not be finished, because the store could not be read	error	On start-up the plugin could not read the store to finish plays a previous run left running. They stay on the file and the next start tries again. Recording itself was not affected.
Handling {What} for play session {PlaySessionId} failed. The event was dropped and the server was not affected	error	One playback event faulted. That one event is lost; the server is not.
A {What} arrived for play session {PlaySessionId} with no start this plugin saw	warning	An event arrived for a play whose start the plugin never saw, for instance a play that began before it was loaded. No row was written.
A play was not stored, because {OccurrenceClass}. Further plays lost the same way are counted and not logged	error	A write to the store failed. The first of a kind is logged and the rest are counted, so a broken store does not fill the log.
The stored configuration was written in shape version {StoredVersion} and has been moved to version {PluginVersion}	information	An upgrade moved the settings file forward. Once, on the start that moved it.
The stored configuration is at shape version {StoredVersion} and this plugin writes version {PluginVersion}. It was written by a later version of this plugin	error	The settings file came from a newer build. It is left alone and settings cannot be saved until this plugin is upgraded again or the file is removed.
The stored configuration at {Path} could not be moved to shape version {PluginVersion}	error	The migration failed. The plugin runs on whatever the server was able to read from the file.
A save was refused. The value sent for {Fields} is outside what this plugin accepts	error	The settings save above. It names the field, which the page deliberately does not.
The plugin's data at {Path} could not be removed while uninstalling	error	A file was held open during the uninstall. It is still on disk and can be deleted by hand.
The plugin's data folder is the folder it was installed into, so it is left for the server's own removal to delete: {DataFolderPath}	warning	Expected where the plugin was installed by hand. The server deletes that folder itself immediately afterwards.

Play session identifiers are opaque strings the server made up for one playback and they mean nothing once the server has forgotten them. The rule the log is held to, and what enforces it, is docs/what-the-log-contains.md.

A report says a row was withheld

A row that fewer than two accounts stand behind is withheld or folded into one group rather than shown, so a server-wide answer cannot become a statement about one person by having only one person in it. On a server with one account, that is every row.

A statistics page is nowhere in the dashboard

Expected. The installed version declares its settings page and nothing else. Pages says why and what is coming.