Troubleshooting

Systematic Reviewer - Research Preview is still a preview build. If a small error blocks a project, first capture the symptom, the project action you were trying, and any visible error text.

Report a bug

Open an issue on GitHub with the Zotero version, operating system, Systematic Reviewer version, what you clicked, what you expected, and the exact error message if one appeared.

Response time. Systematic Reviewer is currently developed by solo researcher Dr Rutkauskas and is not a primary job, so there may be delays in resolving issues. If speed is important and you are comfortable using local development tools, the fastest route may be to ask a coding agent to inspect the XPI and fix the specific issue using the guidance below.

Submit a GitHub issue

Use a coding agent to inspect a local XPI

If you already use a coding agent such as Codex, OpenCode, Claude Code, or another local development assistant, you can ask it to inspect the installed XPI and fix a specific blocking issue. The prompt below gives the agent the important constraints so it does not treat the plugin like a Node web app.

Copyable repair prompt 
You are helping fix Systematic Reviewer, a third-party Zotero plugin. Zotero runs on Mozilla/Gecko. The plugin code runs inside Zotero/Mozilla APIs, not Node, and the plugin must not gain new external dependencies unless the user explicitly asks.

The .xpi file is a renamed .zip archive. Unzip the XPI or open the source tree, inspect the actual code, and fix this specific issue:

[Describe the exact symptom, error text, and the action that triggered it.]

Important constraints:
- Do not invent a new architecture. Fix the specific error.
- Do not assume browser/Electron/Node behaviour where Zotero/Mozilla APIs are required.
- The Writer save/edit/DOM controller code is fragile. Do not touch Writer controller, save, editor, raw, preview, or mode-switching logic unless the bug truly requires it. If those areas are touched, expect regressions and test mode switching carefully.
- REPORT.md is the canonical source of truth for the report. Editor and Raw modes must write back to REPORT.md.
- If this is on Windows, first inspect whether the error comes from UNIX-like assumptions in paths, process execution, file URLs, or shell commands.
- Keep changes narrow, build the XPI, and explain exactly what changed and how it was tested.

Before changing code

  • If the agent consistently fails tool calls, repeats the same mistake, or seems stuck, start a new chat session and ask the task again before trying deeper fixes.
  • Restart Zotero and try the same action once more.
  • Check Jobs if the action was an export, conversion, harvest, embedding, extraction, or semantic-search run.
  • Copy the exact error message. Screenshots are useful when the problem is visual or modal-related.
  • Do not delete project files unless you are sure they are no longer needed.

Research-preview expectations

Preview builds are intended to make new workflows available early. They may still contain platform-specific bugs, especially outside the macOS Zotero environment where most testing has happened so far.

Back to install