Collect debug logs
Gather a template error report, ZotLit logs, Zotero debug output, and Obsidian debug info to include when reporting a bug.
Bug reports often need a template error report, ZotLit logs, Obsidian logs, or Zotero debug output from ZotLit Companion, the Zotero add-on. 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.
Template error report
Collect this when a template preview fails in the Template Workbench. The report holds the template engine's own message and the context of the attempt that failed, so another person can investigate the actual failure.
Open the problem
In the Template Workbench, select Show problem in the preview or on the source marker. The Problems area explains the failure.
Copy the report
Select Copy error report. Select Technical details first if you want to read the report before you copy it: the disclosure shows the same text.
The report holds the engine message, the error name, its causes, any source excerpt, and the location the engine named. Beside those it records the time of the failure, whether an automatic check or Run started it, the template document and section, the template language, the preview root and its options, the selected item or example, the source revision, and the ZotLit and Obsidian versions. A value the failed attempt could not supply reads unavailable.
Paste it into the report
Paste the copied text into your bug report. Nothing leaves your vault until you paste it yourself.
The report survives the repair
Keep working on the template. The copied report describes the attempt that failed, so later edits and a different selected item do not change it. After a successful repair, the open Problems area offers Copy last error report for the failure you were reading.
Ask the community
Ask the community sits beside the copy action and opens the community page. It opens a page; it sends nothing.
When to add more evidence
The copied report covers one failed template attempt. Collect one of the following as well when it applies:
- ZotLit logs: the failure has no engine message, or it happens while creating or updating a note rather than in the preview.
- Template data: the template rendered without failing, but produced the wrong content.
- Obsidian debug info: the problem may involve another plugin, a theme, or a specific Obsidian build.
Each one is a separate collection step. The copied report never carries a log archive or a template-data export.
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 Advanced settings
In Obsidian, open Settings > ZotLit > Advanced and find the Logging group.
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 > Advanced, select 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 Console 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 Console log level back to its previous value after collecting the output.
See also
Last updated on