# Troubleshooting Common Issues When Syncing Zotero Annotations to Obsidian ## Quick Answer - Missing annotations usually trace to the Zotero PDF reader being used instead of the Zotero desktop app, so verify the annotation source before adjusting Obsidian plugin settings. - Duplicate notes appear when both the Zotero Integration plugin and the Zotero desktop sync are exporting the same item, so disable one export path. - Broken links most often come from stale cache files or a changed Zotero storage path, so clear the plugin cache and confirm the Zotero data directory location. ## Understanding the Zotero to Obsidian Sync Pipeline The workflow that moves annotations from Zotero into Obsidian depends on three separate components working together. The Zotero desktop application stores your library and annotations in a local data directory. The Zotero Integration plugin for Obsidian reads that local data and converts it into Markdown notes. The Obsidian vault then stores those notes as plain text files that link to your Zotero items through unique identifiers. Each component has its own settings, cache, and failure points. When you troubleshoot, you need to isolate which part of the pipeline is failing instead of changing settings randomly. The most common errors fall into three categories: annotations never appear, notes appear multiple times, or links break after the notes are created. The Zotero Integration plugin does not sync directly with the Zotero cloud. It reads from the local Zotero data folder on your computer. This means your Zotero desktop app must be installed, logged into the same account, and have the relevant items downloaded locally. If you only have items in the Zotero cloud and not on your local machine, the plugin cannot see them. ## At a Glance | Symptom | Most Likely Cause | First Action | Escalation If Not Resolved | | --- | --- | --- | --- | | Annotations missing from imported notes | Annotations made in Zotero PDF reader instead of desktop app | Reopen the PDF in Zotero desktop and verify annotation icons appear | Check Zotero storage path and plugin log files | | Duplicate notes for the same source | Both Zotero sync and Obsidian plugin exporting the same item | Disable automatic export in one of the two tools | Review plugin import history and remove orphaned notes | | Broken links between Obsidian note and Zotero item | Zotero item key changed or cache is stale | Clear plugin cache and reimport the item | Confirm the Zotero data directory has not been moved | | Notes import but formatting is garbled | PDF annotation extraction failed on complex layouts | Export the annotation as a note from Zotero directly | Update Zotero and the plugin to current versions | | Plugin shows no items in the picker | Zotero desktop is not running or API is blocked | Launch Zotero desktop and check the plugin connection | Verify firewall settings and Zotero version compatibility | ## Core Principles of Reliable Annotation Transfer ### The Zotero Item Key Is the Anchor Every Zotero item has a unique key, a string of letters and numbers that identifies it in your library. The Obsidian plugin uses this key to create the link between your Markdown note and the Zotero item. When you import a note, the plugin embeds this key in the note frontmatter or as a link. If the key changes, the link breaks. Zotero keys do not change under normal use. They change when you merge duplicate items, restore a library from a backup that used different keys, or move items between libraries. If you have done any of these actions, the Obsidian notes that reference the old keys will no longer link correctly. The practical fix is to reimport the item after any library restructuring. The plugin will create a new note with the current key. You can then delete the old note or update its frontmatter manually. ### Local Storage Is the Source of Truth The Zotero Integration plugin reads from the local Zotero data directory. This directory contains your library database, PDF files, and annotation data. The default location depends on your operating system, but you can find it in Zotero by opening Preferences, then Advanced, then Files and Folders. If you have moved this directory, changed your computer, or used a cloud sync service to mirror the folder, the plugin may not find it. The plugin has a setting for the Zotero data directory path. Verify that this path matches the actual location on your system. Cloud sync services like Dropbox or OneDrive can cause problems if they lock files or sync partially. Zotero does not officially support storing your data directory on a cloud drive. If you use this setup, you may see intermittent failures where some annotations import and others do not. ### The Plugin Cache Stores Import History The Zotero Integration plugin keeps a cache of items it has already imported. This cache prevents duplicate imports and speeds up the picker. When the cache becomes stale or corrupted, you see two problems. The plugin may skip items you want to reimport, or it may import duplicates because the cache lost track of what was already processed. Clearing the cache is a safe troubleshooting step. The plugin will rebuild it on the next import. You lose no data because the cache only stores import metadata, not your actual notes. ## Practical Workflow for Diagnosing Sync Failures ### Step 1 Confirm the Annotation Exists in Zotero Desktop Open Zotero desktop and navigate to the item you expect to have annotations. Click on the PDF attachment. In the right-hand pane, you should see a tab for annotations. If the annotation list is empty, the annotations were not saved to the Zotero library. The most common reason annotations are missing is that they were made in the Zotero PDF reader, a separate browser-based tool, instead of in the Zotero desktop PDF viewer. The Zotero PDF reader stores annotations in your Zotero account, but the Obsidian plugin cannot read them because they are not in the local data directory. To fix this, open the PDF in Zotero desktop, select the text you want to annotate, and create a new highlight or note. Save the item. The annotation should now appear in the right-hand pane. After this, the Obsidian plugin can import it. ### Step2 Verify the Plugin Connection to Zotero In Obsidian, open the Zotero Integration plugin settings. Look for a status indicator that shows whether the plugin can communicate with Zotero. If the status shows disconnected, the plugin cannot read your library. Zotero desktop must be running for the plugin to work. The plugin uses the Zotero local API, which is only available when the desktop app is open. If you close Zotero to save memory, the plugin will not find any items. If Zotero is running and the plugin still shows disconnected, check the Zotero data directory path in the plugin settings. This path must point to the folder that contains the zotero.sqlite file. If the path is wrong, the plugin cannot access the library database. ### Step3 Clear the Plugin Cache and Reimport If annotations exist in Zotero and the plugin is connected, the next step is to clear the cache. In the plugin settings, find the option to clear the import cache. Confirm the action. Then open the plugin picker and search for the item again. The plugin will now treat the item as new and import all annotations it finds. If the note still comes in without annotations, the problem is in the PDF extraction step, not the cache. ### Step4 Test with a Simple Item Create a new Zotero item with a single PDF that has one highlight. Import that item into Obsidian. If the annotation appears, the pipeline works and the problem is specific to certain PDFs. If the annotation does not appear, the problem is in the plugin configuration or the Zotero installation. This test isolates the issue. A simple item removes variables like complex PDF layouts, multiple authors, or large file sizes. You can then compare the failing PDF with the working one to identify what is different. ## Common Failure Patterns and Their Fixes ### Missing Annotations on Imported Notes When a note imports but contains no annotations, the plugin found the item but could not extract the annotation data. This happens in several situations. The first situation is that the annotations were made in the Zotero PDF reader. As described above, these annotations live in the cloud and are not available to the local plugin. The fix is to recreate the annotations in Zotero desktop. The second situation is that the PDF has a complex layout with columns, tables, or embedded images. The extraction algorithm may fail to map the highlighted text to the correct location. In this case, you can manually copy the annotation text from Zotero and paste it into the Obsidian note. The third situation is that the annotation is a note attached to a region of the PDF instead of a text highlight. Image-based annotations, such as area highlights, do not always export as text. The plugin may skip them because there is no text to extract. ### Duplicate Notes Appearing in the Vault Duplicate notes have two common causes. The first is that you have both the Zotero Integration plugin and another sync tool, such as the Zotero desktop sync or a third-party plugin, exporting the same item. Each tool creates its own note file. The second cause is that you imported the item, then cleared the cache, then imported it again without deleting the first note. To resolve duplicates, decide which tool will be your primary import path. Disable automatic export in the other tool. Then delete the duplicate notes manually. Keep the note that has the correct frontmatter and links. To prevent future duplicates, do not clear the cache unless you intend to reimport and replace existing notes. If you need to refresh a note, delete the old note first, then import fresh. ### Broken Links Between Obsidian and Zotero A broken link appears when the Obsidian note references a Zotero item key that no longer exists in your library. This happens after library restructuring, as described earlier. It also happens when you restore a Zotero library from a backup that was created before you added the item. The fix is to find the current item key in Zotero and update the Obsidian note. You can see the item key in Zotero by right-clicking the item, selecting Copy Citation, and looking for the key in the citation code. Alternatively, reimport the item and copy the new frontmatter into the old note. ### Plugin Shows No Items in the Picker If the plugin picker is empty, the plugin cannot read your library. Check the connection status first. If the status is connected but the picker is empty, the plugin may be filtering by collection or saved search. Review the plugin settings for any filters that exclude the items you expect to see. Another cause is that your Zotero library is very large and the plugin has not finished indexing. Wait a few minutes and try again. If the picker remains empty, restart both Zotero and Obsidian. ### Formatting Issues in Imported Notes Some PDFs have annotations that import with extra line breaks, missing spaces, or garbled characters. This is usually a PDF extraction issue, not a plugin issue. The text layer of the PDF may be poorly constructed, especially in scanned documents or PDFs generated from certain typesetting software. You can work around this by copying the annotation text directly from Zotero and pasting it into the Obsidian note. The formatting will match what you see in Zotero. For scanned PDFs, consider using optical character recognition in Zotero before annotating. ## Records and Measurements for Tracking Sync Health ### What to Record Keep a simple log of your sync activities. This log helps you identify patterns and speeds up troubleshooting when problems recur. Record the date, the Zotero item key, the action taken, and the result. | Date | Zotero Item Key | Action | Result | | --- | --- | --- | --- | | 2025-01-15 | ABC123DEF | Imported note | Success, 3 annotations | | 2025-01-16 | ABC123DEF | Cleared cache, reimported | Duplicate created, deleted old note | | 2025-01-17 | GHI456JKL | Imported note | Missing annotations, recreated in desktop | ### What to Measure Measure the time between adding an annotation in Zotero and seeing it in Obsidian. This should be near instant if both apps are open. If there is a delay, the plugin may be polling on a longer interval or the library may be large. Measure the number of annotations per note against the number you expect. If the counts do not match, you have a missing annotation problem. Track which PDFs consistently fail so you can identify a pattern. ### When to Escalate If you have followed the troubleshooting steps and the problem persists, escalate to the plugin developer or the Zotero support forum. Before you post, gather your log entries, the Zotero version, the Obsidian version, the plugin version, and a description of the failing PDF. This information lets others reproduce the issue. Escalate immediately if you suspect data loss. If notes are being deleted or overwritten, stop using the plugin and restore from your Obsidian backup. Data loss is rare but possible if you have a sync conflict between Obsidian sync and the plugin. ## Options and Tradeoffs in Sync Configuration ### Automatic Import Versus Manual Import The plugin can import notes automatically when you add an item to a specific collection, or you can import manually using the picker. Automatic import saves time but creates notes for every item in the collection, including ones you may not want. Manual import gives you control but requires you to remember to do it. For most users, manual import is safer. You see each note before it is created and can skip items that do not need a note. Automatic import is useful when you have a dedicated collection for items you always want in Obsidian. ### Single Note Versus Per Annotation Notes The plugin can create one note per Zotero item with all annotations, or one note per annotation. A single note keeps your vault organized by source. Per annotation notes create more files but allow you to link each annotation to different topics. Per annotation notes are useful for literature reviews where you want to tag each finding separately. Single notes are better for building a library of source summaries. You can change this setting at any time, but existing notes will not be restructured automatically. ### Citation Key Format The plugin uses a citation key format to name notes and create links. The default format uses the first author last name and year. You can customize this to include the title or a short identifier. Choose a format that is stable. If you change the format later, existing note names will not update, and you may have to rename files manually. A stable format uses the Zotero item key, which never changes. The downside is that item keys are not human readable. A format with author and year is readable but can collide if you have two items by the same author in the same year. ## Welfare and Safety Context for Research Integrity ### Accurate Annotation Transfer Supports Research Integrity The reason you sync annotations to Obsidian is to build a reliable record of what you read and what you concluded. If annotations are missing or links are broken, your notes may misrepresent the source. This matters for research integrity because your notes are the basis for citations and conclusions in your writing. The Committee on Publication Ethics core practices emphasize accurate reporting and proper attribution. When your notes do not accurately reflect the source, you risk unintentional misattribution. A broken link may lead you to cite the wrong paper or misquote a finding because you cannot verify the original context. ### Data Management and Sharing Expectations If your research is funded by the National Institutes of Health, you are subject to the NIH Data Management and Sharing Policy. This policy expects you to preserve and share the data that underlies your findings. Your annotation notes are part of your research record. If they are incomplete or corrupted, your ability to document your research process is weakened. The NIH policy also expects you to plan for data management before you start your research. Your note-taking workflow is part of that plan. A reliable sync between Zotero and Obsidian supports your ability to meet these expectations because it keeps your annotations accessible and organized. ### Researcher Identity and Record Keeping ORCID provides a persistent identifier for researchers. Your ORCID record links your publications and research activities. The notes you take in Obsidian feed into your writing and eventually into your publications. If your notes are unreliable, your publication record may suffer. Maintaining a clean sync workflow is part of professional record keeping. It ensures that the sources you cite are the sources you actually read and annotated. This is a basic expectation of research integrity and is reinforced by the reporting guidelines available through the EQUATOR Network. ## Limitations of the Sync Workflow ### The Plugin Does Not Sync Annotations From the Zotero PDF Reader This is the most important limitation to understand. The Zotero PDF reader is a separate tool that stores annotations in the cloud. The Obsidian plugin reads only from the local Zotero data directory. If you use the PDF reader for most of your annotation work, the plugin will not see those annotations. You have two options. Use the Zotero desktop PDF viewer for annotations you want in Obsidian, or manually export annotations from the PDF reader and paste them into Obsidian. The first option is more efficient if you rely on Obsidian for your notes. ### The Plugin Does Not Handle All PDF Annotation Types Image-based annotations, such as area highlights and freehand drawings, do not export as text. The plugin may skip them or import them as empty placeholders. If you use these annotation types, you need to handle them manually. Text highlights and text notes export reliably. If your workflow depends on image annotations, consider whether you need them in Obsidian or whether they can stay in Zotero only. ### The Plugin Requires Zotero Desktop to Be Running The plugin cannot read your library if Zotero desktop is closed. This means you cannot import notes while Zotero is not running. If you prefer to keep Zotero closed to save memory, you need to open it before importing. This limitation is by design. The plugin uses the Zotero local API, which is only available when the desktop app is running. There is no workaround for this within the plugin. ## Professional Escalation Criteria ### When to Contact the Plugin Developer Contact the plugin developer when you have a reproducible bug. A reproducible bug is one that happens every time you perform a specific action. For example, if importing any PDF with a table always produces garbled text, that is a reproducible bug. Before contacting the developer, gather your system information. Include the Zotero version, the Obsidian version, the plugin version, and your operating system. Describe the exact steps you took and what you expected to happen. This information helps the developer identify the cause. ### When to Contact Zotero Support Contact Zotero support when the problem is in the Zotero application itself. This includes issues with the Zotero data directory, the Zotero desktop PDF viewer, or the Zotero sync service. If the plugin cannot read your library because Zotero is not functioning correctly, Zotero support is the right place. Zotero support can help you repair a corrupted library database, recover a lost data directory, or resolve sync conflicts. These issues are outside the scope of the Obsidian plugin. ### When to Restore From Backup Restore from backup when you suspect data loss. If notes are being deleted, overwritten, or corrupted, stop using the plugin immediately. Restore your Obsidian vault from your most recent backup. Then reimport your Zotero items fresh. You should also restore from backup if your Zotero library database is corrupted and you cannot repair it. Zotero creates automatic backups of your library database. You can find these backups in your data directory and restore the most recent one. ## Frequently Asked Questions ### Why are my Zotero annotations not showing up in Obsidian? The most common cause is that the annotations were made in the Zotero PDF reader instead of the Zotero desktop app. The Obsidian plugin reads only from the local Zotero data directory, and PDF reader annotations are stored in the cloud. Recreate the annotations in Zotero desktop and reimport the item. ### How do I stop duplicate notes from appearing in Obsidian? Duplicate notes appear when two tools export the same item or when you reimport after clearing the cache. Choose one import path and disable the other. Delete existing duplicate notes manually. Do not clear the cache unless you intend to replace existing notes. ### Why are my Obsidian links to Zotero items broken? Broken links happen when the Zotero item key changes. This occurs after merging duplicate items, restoring from a backup, or moving items between libraries. Reimport the item to get the current key and update the Obsidian note frontmatter. ### Can I sync annotations from the Zotero PDF reader to Obsidian? No, the Obsidian plugin cannot read annotations from the Zotero PDF reader. These annotations are stored in the cloud and are not available to the local plugin. Use the Zotero desktop PDF viewer for annotations you want in Obsidian, or paste the annotation text manually. ### Why does the plugin picker show no items? The plugin cannot read your library if Zotero desktop is not running or if the data directory path is wrong. Check the connection status in the plugin settings. Verify that Zotero is open and that the data directory path points to the folder containing the zotero.sqlite file. ### What should I do if my imported notes have garbled formatting? Garbled formatting usually comes from a poorly constructed text layer in the PDF. This is common in scanned documents. Copy the annotation text directly from Zotero and paste it into Obsidian. For scanned PDFs, run optical character recognition in Zotero before annotating. ### How often should I clear the plugin cache? Clear the cache only when you need to reimport an item that was already imported. The cache prevents duplicate imports and speeds up the picker. Clearing it unnecessarily can lead to duplicate notes if you do not delete the old notes first. ### Does the plugin work if I store my Zotero data directory on a cloud drive? Zotero does not officially support storing the data directory on a cloud drive. You may see intermittent failures where some annotations import and others do not. Use the default local data directory location for reliable sync. ## Related Articles - [PCR Troubleshooting: A Decision Framework for Weak, Missing, or Nonspecific Bands](/blog/guides/pcr-troubleshooting-a-decision-framework-for-weak-missing-or-nonspecific-bands) - [Ethical Issues in Informed Consent: Common Pitfalls and How to Avoid Them](/blog/guides/ethical-issues-in-informed-consent-common-pitfalls-and-how-to-avoid-them) - [Gene Ontology Enrichment Analysis: Avoiding Common Interpretation Errors](/blog/guides/gene-ontology-enrichment-analysis-avoiding-common-interpretation-errors) - [Biology Notes](/blog/careers/biology-notes) - [Western Blot Troubleshooting](/blog/guides/western-blot-troubleshooting) ## References and Further Reading - [Research Methods Resources](https://www.ncbi.nlm.nih.gov/books). National Library of Medicine. - [EQUATOR Network](https://www.equator-network.org/). EQUATOR Network. - [Core Practices](https://publicationethics.org/core-practices). Committee on Publication Ethics. - [NIH Grants and Funding](https://grants.nih.gov/). National Institutes of Health. - [ORCID for Researchers](https://info.orcid.org/researchers). ORCID. - [Data Management and Sharing Policy](https://sharing.nih.gov/data-management-and-sharing-policy). National Institutes of Health. - [NCBI Literature Resources](https://www.ncbi.nlm.nih.gov/). National Center for Biotechnology Information. - [PubMed](https://pubmed.ncbi.nlm.nih.gov/). National Library of Medicine. > This article is educational and does not replace institutional policy, professional advice, or applicable safety and regulatory requirements.