Translations of this page:

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 for Firefox or Zotero Standalone

  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 preferences.)
  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

For large amounts of output, “Submit to Zotero Server” may return an error. If so, click “Open about:config” in the Advanced pane of the Zotero preferences, search for extensions.zotero.debug.store.submitSize, double-click it, and reduce its value to “500000”. Then try to submit the output again.

Real-time Debug Output

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

Mac OS X

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

  • Open Terminal in /Applications/Utilities
  • Go to the Terminal menu and open Preferences. In Profiles→Window, make sure Scrollback is set to “Limit to available memory”.
  • Paste "/Applications/Firefox.app/Contents/MacOS/firefox-bin -ZoteroDebug" (Firefox) or "/Applications/Zotero.app/Contents/MacOS/zotero-bin -app /Applications/Zotero.app/Contents/Resources/application.ini -ZoteroDebug" (Standalone), without quotes, into the Terminal window
  • Press Return

You should see debug output in the console as Zotero starts.

To capture output for a particular action (e.g., for a translator save attempt), press Cmd-K in the Terminal to clear all previous output before performing the action and then copy the complete output immediately afterwards.

If you receive the message “Command not found” in the Terminal, the location of Firefox on your system may be slightly different, or you may have entered the above line incorrectly. Ctrl-click on the icon you use to open Firefox and select Show in Finder. Look at the name of the Firefox application and the folder it is in. Replace “Firefox” in the line above with the name you see in the Finder. If Firefox is not located in the Applications folder, press Command-I and look at the “Where:” field to see the full path, and replace “/Applications” in the above line with that path. If there are any spaces in the path or app name, you'll need to surround the entire path with quotation marks. For example, if Firefox is named “Firefox 24”, you might use this line (quotation marks included):

"/Applications/Firefox 24.app/Contents/MacOS/firefox-bin" -ZoteroDebug

If you receive the message “dyld: unknown required load command 0x80000022 Trace/BPT trap” in the Terminal, use this command instead:

arch -i386 /Applications/Firefox.app/Contents/MacOS/firefox-bin -ZoteroDebug

Windows

Note: Real-time debug output on Windows slows down Zotero.

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

  • Start, Run (or Windows key + R). Click Browse and locate Firefox or Zotero Standalone:
    • Firefox is typically located at "C:\Program Files (x86)\Mozilla Firefox\firefox.exe" or "C:\Program Files\Mozilla Firefox\firefox.exe"
    • Zotero Standalone is typically located at "C:\Program Files (x86)\Zotero Standalone\zotero.exe" or "C:\Program Files\Zotero Standalone\zotero.exe"
  • Select the appropriate file and click Open.
  • In the Run box, append the following to the very end of the text, after any quotes if present:
    • Zotero for Firefox
      • " -jsconsole -ZoteroDebug"
    • Zotero Standalone:
      • " -console -ZoteroDebug"
    • (Do not include the quotes, and note the space before each hyphen.)
  • Click OK.

You should see debug output in the Browser Console (Firefox) or text console (Standalone) as Zotero starts.

To copy output to the clipboard in Firefox, after performing the relevant action (e.g., saving via a translator), right-click within the console and choose Select All, and then right-click again and choose Copy.

To copy output in Standalone, select text and right-click to copy it.

If you cannot locate Firefox or Zotero Standalone, find an existing shortcut to Firefox/Zotero Standalone (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 Start→Run, 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 '-console -ZoteroDebug' (without quote marks).

Linux

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

You should see debug output in the console as Zotero starts. After performing the relevant action (e.g., saving via a translator), immediately copy the complete content to the clipboard.

Developer Note

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