This is an old revision of the document!


Debug Output Logging

If you've been asked to provide a Debug ID (which is different from a Report ID) to help troubleshoot a problem, follow these simple steps:

Zotero 5 and later

  1. In the Help menu, go to Debug Output Logging and select Enable, or use “Restart with Logging Enabled…” to generate debug output from Zotero startup.
  2. Immediately perform the relevant action (syncing, saving, importing, etc.).
  3. Before doing anything else, return to Help → Debug Output Logging and click Submit Output, which will disable logging and submit the output to zotero.org. A window should pop up containing a Debug ID (e.g., “D12345678”). Click “Copy to Clipboard” and paste the Debug ID into your forum thread.

Zotero 4 for Firefox

  1. Open the Advanced pane of the Zotero preferences. You can access the Zotero preferences from the gear menu in the Zotero toolbar. (In Zotero for Firefox, you can also access the Zotero preferences via the Firefox Add-ons pane.)
  2. Click “Enable” under Debug Output Logging.
  3. Immediately perform the relevant action (syncing, saving, importing, etc.).
  4. Before doing anything else, click “Submit to Zotero Server” in the Advanced pane of the preferences. After uploading the output, Zotero will provide a Debug ID (e.g., “D12345678”) that you can post to the forums. There's no need to post the actual debug output.
  5. Disable debug output logging and click “Clear Output”.

Zotero Connectors (Firefox, Chrome, and Safari)

  1. Open the Zotero Connector preferences
    • Firefox: type about:addons into the address bar, press return, and click the “Preferences” button next to the entry for “Zotero Connector”.
    • Chrome: type chrome://extensions into the address bar, press return, and click the “Options” link underneath “Zotero Connector.”
    • Safari: right-click anywhere on a webpage and select “Zotero Preferences…”
  2. In the Advanced tab of the Zotero Connector preferences, check the box next to “Enable Logging.” Do not close this window.
  3. Immediately perform all the relevant actions (e.g., import an item from a web page).
  4. Go back to the Advanced tab of the Zotero Connector preferences and click Submit to Zotero Server.
  5. You will be provided with a Debug ID (e.g., “D12345678”). Please post the Debug ID to the forums.
  6. Uncheck the box next to “Enable Logging.”

Error Submitting a Debug Log

Zotero 5.0.8 and later

If submitting output fails, you can return to the Debug Output Logging menu and select View Output, go to File → “Save…”, choose Format: “Text Files”, and save the output to a file, which you can email to support@zotero.org with a link to your forum thread. It can be helpful to ZIP the file before emailing it.

Real-time Debug Output

If you'd like to follow Zotero's debug output in real-time, you'll need to start Zotero from the command line.

macOS

Close Zotero and then restart it via the command line:

  • Open Terminal via Spotlight or /Applications/Utilities.
  • Paste "/Applications/Zotero.app/Contents/MacOS/zotero -ZoteroDebug", without quotes, into the Terminal window. Note the space before the hyphen.
  • Press Return

Zotero should start up with a separate window that shows debug output and allows you to easily submit the output and create a Debug ID for posting to the forums.

To capture output for a particular action (e.g., for a translator save attempt), press Clear before performing the action and then submit the output immediately afterwards.

If for some reason the debug window doesn't work, you can also pass -ZoteroDebugText in order to display the output directly in Terminal.

If you receive the message “Command not found” in the Terminal, the location of Zotero on your system may be different, or you may have entered the above line incorrectly. Ctrl-click on the icon you use to open Zotero and select Show in Finder, and then drag the Zotero icon into Terminal. You can then add the rest of the line above immediately after the “.app”.

Windows

Close Zotero, and then restart it via the command line:

  • Press Windows + R or search for 'run' to open the Run window. Click Browse and locate Zotero (typically located at "C:\Program Files (x86)\Zotero\zotero.exe")
  • Select the appropriate file and click Open.
  • In the Run box, append " -ZoteroDebug" (without quotes) to the very end of the text, after any quotes if present. Note the space before the hyphen.
  • Click OK.

Zotero should start up with a separate window that shows debug output and allows you to easily submit the output and create a Debug ID for posting to the forums.

To capture output for a particular action (e.g., for a translator save attempt), press Clear before performing the action and then submit the output immediately afterwards.

If you cannot locate Zotero, find an existing shortcut to it (e.g., on your desktop or in the Start menu), right-click it, select Properties, make sure the Target field is selected, and copy it to the clipboard by pressing Ctrl-C. Click Cancel to close the shortcut window. Back in the Run window, clear the field and paste in the clipboard by pressing Ctrl-V. At the end of the field, after the second quotation marks, add a space followed by '-ZoteroDebug' (without quote marks).

Linux

Close Zotero, and then restart it via the command line, adding the -ZoteroDebug command-line flag.

Zotero should start up with a separate window that shows debug output and allows you to easily submit the output and create a Debug ID for posting to the forums.

To capture output for a particular action (e.g., for a translator save attempt), press Clear before performing the action and then submit the output immediately afterwards.

If for some reason the debug window doesn't work, you can also pass -ZoteroDebugText in order to display the output directly in the terminal.

Developer Note

To enable Zotero debug output permanently, set extensions.zotero.debug.log to true in the Zotero config editor, accessible from the Advanced pane of the Zotero preferences, and then start Zotero from the command line.