Collect debug logs
Gather ZotLit logs, Zotero debug output, and Obsidian debug info to include when reporting a bug.
Available sinceZotLit 2.0.0
Bug reports often need logs from ZotLit, from the ZotLit companion, or from Obsidian itself. Each section below is self-contained. Follow only the one you were asked for.
Once you have the logs, file the report in the Bug reports discussion.
Cross-component bugs need both sides
If the bug spans ZotLit and the companion (e.g. syncing, live update, importing, or any action that rely on Zotero running), complete the setup steps in both ZotLit logs and Zotero debug output before you reproduce the problem. Reproduce once, then save logs from both sides.
Obsidian debug info
Run the debug info command
Open the command palette and run Show debug info.
Copy the output
Copy the output and paste it into the issue.
ZotLit logs
Open the Maintenance settings
In Obsidian, open Settings > ZotLit > Maintenance.
Turn on debug logging
Set Log level to debug, then turn on Write logs to file. Logs now append to zotlit.log.jsonl inside the plugin folder.
Reproduce the problem
Do whatever triggers the bug.
Save the log archive
Back in Settings > ZotLit > Maintenance, click Save log archive. This exports the log file for sharing.
Upload the archive
Attach the saved archive to your bug report.
Turn logging back off
Set Log level back to info and turn off Write logs to file once you no longer need ongoing logging.
Template data
Collect this when a template rendered the wrong thing. The saved file holds the exact data your templates received for one item.
Open the explorer on the item
Open the Template Data Explorer on the item that reproduces the problem.
Anchor at the annotation
If the problem is in an annotation template, open the more-options menu on that annotation node in the tree and select Explore as annotation template data. For any other template, skip this step and stay at the note root.
Save the template data
Open the more-options menu on the explorer's tab and select Save template data as JSON. This downloads a file named like zotlit-template-data-ABCD2345-20260512-143000.json.
The file always holds the whole current root: the full note template data at the note root, or the annotation's data when the explorer is anchored at an annotation. A filter in the explorer does not narrow it.
Upload the file
Attach the saved file to your bug report.
Read the file before you share it
The file contains Zotero library metadata for the item, absolute paths to attachments inside your Zotero data folder, and your Zotero account username. Review it before you attach it to a public bug report.
Placeholder markers are expected
The explorer never writes files into your vault, so helpers that normally
create them, such as annotation excerpt images and imported child notes,
produce placeholder markers instead of real links. These appear as $inert
entries in the file, and helpers appear as $helper entries. Both are
expected in the saved data.
Zotero debug output
Set the companion's log level
In Zotero, open Edit > Settings (Windows/Linux) or Zotero > Settings (macOS), then select the ZotLit pane. Set Log level to Debug.
Restart Zotero with logging enabled
Go to Help > Debug Output Logging and click Restart with Logging Enabled….
Do not use troubleshooting mode
A confirmation dialog appears. Do not select Restart in Troubleshooting Mode: that mode disables all add-ons, including the companion, so no debug output would be captured.
Reproduce the problem
As soon as Zotero restarts, reproduce the problem.
Open the debug output viewer
Go to Help > Debug Output Logging > View Output.
Save the output
In the viewer, go to File > Save…, choose Format: Text Files, and save the output.
Do not use Submit Output or Copy to Clipboard. The full log file is needed.
Upload the file
Attach the saved text file to your bug report.
Reset the log level
Set the companion's Log level back to its previous value after collecting the output.