How to post a helpful, i.e. precise, bug report, question, etc.?

If you want us to help you, you need to be as specific as possible when you report a bug or ask a question. Tell us your operating system, the version of Docear or Docear4Word, and provide step-by-step instructions with exact examples that allow us to reproduce the bug or understand your question. Being precise is in your own interest. If you are not, it will take us more time to find the problem or answer your question. This means, we will have less time to implement new features and improve Docear. In addition, if we don’t understand what you want from us, and we ask you to explain your issue in more detail, it will delay the final answer for a few days, because we are visiting the forum only once or twice a week. This means, if you ask a question on Monday, and we ask you on Tuesday to explain your issue in more detail, you probably won’t get a follow-up answer before Friday, even if you directly answer on Wednesday. If you had been precise right away, you would have had the final answer on Tuesday already.

Being precise does not mean that you need to write pages over pages. Just provide as many information as possible in the most concise way to enable us to reproduce the bug or understanding exactly what you want to know.

Here are a few (bad) examples.

Hello, I found a bug. When I accidentally enter an incorrect bibtex key, docear opens two popup windows saying invalid BibTeX key entry.

Such a bug report is of little use. In this particular example, we need to know where you have entered the BibTeX key and we also need a an example of an invalid BibTeX key to reproduce the bug.

Another user sent us this

Docear does not start. What can I do?

Again, such a question is not specific enough. We need to know if this is the very first time that you start Docear, or if you have upgraded from an older version. We need to know your operating system. We need to know what exactly you mean by “Does not start”. Is there any error message? Is just nothing happening? Is Docear starting but then the GUI freezes? …?



When should I send a feature request, bug report or question directly to the Freeplane team?

Docear is based on the mind mapping software Freeplane and whenever the Freeplane team is changing something in Freeplane we will automatically incorporate these changes into Docear (with a few weeks delay). We closely cooperate with the Freeplane team and agreed that Freeplane will focus on mind mapping functionality and we on PDF and reference management and the workspace. Therefore, if you have a feature request or find a bug that relates to the core mind mapping functionality, you can directly contact the Freeplane team. Some examples of such functionality is formatting nodes, printing, navigation in mind maps, time and calender management, or the search and filtering function.

Similarily, if you have a question that relates only to the mind mapping functionality (e.g. how to use floating nodes or the calender function, …) you might also ask the Freeplane team because we are not 100% familiar with all the functions that Freeplane offers. Of course, you can also ask us and if we can answer the question we will happily do.


I lost a mind map. How can I restore/recover it?

It has happened that users lost some mind-maps and hence the work of days, weeks, or even months was lost. There is a number of reasons why users lost their data. Some had a virus, others bought a new computer and forgot to make a backup of Docear’s data, and a few just deleted their data by mistake. In very few cases it even happened that Docear deleted mind maps, or overwrote them with 0 byte mind maps (this can happen in particular, if your computer crashes exactly when you save a mind map).

If you lost some data, there is a chance to recover it, but first of all: Do not make any changes on Docear. If Docear is running, do not close it. If Docear is not running, do not start it!

  1. If you have activated Docear’s free online backup feature, you can download your mind maps at “My Mind Maps“.
  2. Sometimes, Docear needs to convert mind maps to a new data format. In these situations, Docear creates a backup. Docear also creates auto-backups while you use Docear, but deletes these backups once you close Docear. These backups are stored in c:\Users\<windows username>\.docear\backup\   (or ~/.docear/backup/ on Linux and and Mac OS X). If you are lucky, there is a copy of your mind maps in this folder.
  3. If you have activated the recommendation feature, your mind maps are also transferred to our server but do not appear at “My Mind Maps”. Contact us, we might be able to recover your mind maps.
  4. If you have activated online backup or recommendations, mind maps that are scheduled to be transferred to our servers, are first stored in c:\Users\<windows username>\.docear\users\<docear username>\queue\mindmaps\ (or ~/.docear/users/<docear username>/queue/mindmaps/ on Linux and Mac OS X). Have a look, maybe you find a copy of your mind map in that folder.
  5. If all the previous steps do not help, you may try the free UndeletePlus. Use it to recover deleted files from c:\Users\<windows username>\.docear\backup\ or c:\Users\<windows username>\.docear\users\<docear username>\queue\mindmaps\backup, or from the other places where you stored your mind-maps. If you are really lucky, this works.

If none of the above steps recover your data there is probably nothing we can do about it. To prevent data loss in the future, we can only recommend to use Docear’s free backup feature, and ideally you use an additional third party tool. We can highly recommend Crashplan, which backups your entire hard drive for only 5$ a month (we don’t get any money for this recommendation but Crashplan has helped ourselves several times to recover important data). Seriously, data loss can always happen – due to your own faults, errors in the soft- or hardware, or simply bad luck. Therefore, please, take some precautions before you lose your valuable work.

What should I know when using Docear on a Linux system?

The Java Virtual Machine (JVM)

Different JVMs come with different strengths and weaknesses when it comes to using them on a Linux system. While Open-JDK versions often had issues with distorted fonts, the older Oracle-Java versions had issues with menus and mouse positioning. While Oracle-JDKs are not open source, version 8 seems to fix both issues and we hence recommend you to use Oracle-JDK-8. You are, of course, free to try Docear with any other version of Java. Please tell us about your experiences.

Compatible PDF viewers

Although the PDF-X-Change Viewer is not open source and cannot natively run on Linux systems, we nevertheless recommend it. It can be installed using WINE and is the only one which supports import of highlighted text. If you run into any errors please read the appropriate section in our manual or this forum discussion.


If you are using Ubuntu and Docear crashes, please read in the forum.

Why is Docear not starting on Microsoft Windows?

A few Microsoft Windows users have trouble to start Docear. These two hints have helped them:

Delete Docear’s installation folder and install Docear again afterwards

When you have used older versions of Docear succesfully, but the new version does not start, you should delete Docear’s installation folder and install Docear again aftwerwards. Docear’s installation folder is located at “C:\Program files\Docear” on 32-Bit or “C:\Program files (x86)\Docear” on 64-Bit systems by default. It contains both the “Docear.bat” and the “Doceat.exe” files.

Tell Docear to use another location in order to store and restore its settings

If your Windows user folder is located on a network drive, which is the default configuration in some companies, Docear won’t find its settings.and can’t start. You can tell Docear to use a different location for this settings folder. In order to do that, please follow these steps:

Please navigate to your installation folder of Docear, i.e. the folder containing both the “Docear.exe” and the “Docear.bat” file (you can find further information at the top of this page). Now copy the Docear.bat file to your Desktop (you won’t be able to modify it in the “C:\Program files” location. Now open it with your default text editor (e.g. right-click it and select modify or edit from the context menu). Do not use any rich text editors like Microsoft Word!
You have to attach an aditional parameter to the command String in order to tell Docear where it should store and restore its settings from. You need to add this entry (including the quotation marks somewhere between other “-D…” entries) and modify the path according to your needs, e.g.:

Now copy the file back to Docear’s installation folder and start it from there.

A full version of this file might look like this:

@echo off
set freeplanedir=%~dp0
set xargs=init.xargs
set defines= “-Dorg.freeplane.param1=%~1” “-Dorg.freeplane.userfpdir=C:\Users\stefan\.docear” “-Dorg.freeplane.param2=%~2” “-Dorg.freeplane.param3=%~3” “-Dorg.freeplane.param4=%~4”
set resdir=”-Dorg.freeplane.globalresourcedir=%freeplanedir%resources/”
@echo on
java -Xmx512m “-Dorg.knopflerfish.framework.bundlestorage=memory” “-Dorg.knopflerfish.gosg.jars=reference:file:%freeplanedir%core/” %resdir% %defines% -jar “%freeplanedir%framework.jar” -xargs “%freeplanedir%props.xargs” -xargs “%freeplanedir%%xargs%”

Why is Docear not starting on Mac OS X?

Mac OS X 10.9.x requires all software to be signed, otherwise you might experience errors and warning messages when trying to start a software. Docear is not signed for Mac OS because Apple charges money for this. Hence, you might receive warning messages or a message that Docear is damaged when you try to start it.  The following solutions might help you. Please note that we don’t have any Mac for testing. Hence, all information is based on what users tell us. If you feel that some information is missing, misleading or whatever, contact us and provide some better information that we can put here.

  • When start Docear for the very first time, you need to change your security settings:  system preferences -> security -> allow apps from anywhere. You can also right-click the app, open it and select that you want to execute it although it is not signed.
  • When you already used Docear and upgrade to a newer version, OS X 10.9.x fails to verify the Docear app and reports that it was tampered.

To solve this issue you need to open a terminal shell and execute the following commands::

sudo spctl --list | grep Docear
This will return a line with an ID and some additional information like this: 3529[UNLABELED] P0 allow execute [/Applications/Docear.app]

Then you need to remove it.
sudo spctl --remove --rule 3529 # e.g. with an id of 3529. It may be different for you.

Next you have to tell the system to put Docear.app back in quarantine to test if the signature is valid again and we can use the right click method again.
xattr -rd com.apple.quarantine /Applications/Docear.app # your app location can be different.

Now the application will open when you right-click it and press OPEN.

Mac OS X 10.10.x (Yosemite): Since we don’t have a Mac for testing and developing, we can only report what users are telling us, and reports are contradicting. Some users use Docear successfully on Yosemite 10.10.x.  However, it seems that many users experience problems. Originally, we thought the problem was caused by one of the software libraries Docear is using (the OSGI framework) which presumably is not compatible with Mac OS X 10.10. There is a version of that library that is compatible with OS 10.10 but upgrading Docear would require massive changes. We currently don’t know when we will have time for this. However, as mentioned, some users run Docear successfully on Mac OS X 10.10 with the ‘old’ software library. One possible solution is explained on StackOverflow, with the solution being to downgrade your Java version (on your own risk).

So, all we can suggest is: Try to run Docear, maybe it works. If it does, let us know how you did it. If it doesn’t… come back in a few months and check if we upgraded Docear to the latest OSGI version, or have some other information on how to run Docear on Mac OS X 10.10.

What is a project and when should I create a new one?

In Docear, you may work with multiple projects that are all listed in your workspace panel. We are often asked what a project is intended for and for what kind of work exactly one should create a new project? We suggest that you create different projects only for entirely different and independent kind of works. For instance, I created a project for Docear’s manual, another project for Docear’s teaser video, and another project for my own PhD thesis. I am not creating new projects for every paper I write (instead, I only create a new mind map within my Thesis project to draft a new paper).

You might think of a project as something you would want to share with others. For instance, I do have my PhD thesis project with all the literature I annotated during the past few years. When I want to write a new paper with my colleague, I wouldn’t mind to give him access to all my literature including annotations, and my other drafts, because my colleague would need access to most of my literature, and maybe even to old drafts, to write the current paper. Therefore, all my literature and drafts that somehow relate to my PhD thesis are in one project, and I do share the entire project with my colleague via Dropbox.

Now, for Docear’s manual I needed to create many examples that do not have anything to do with my thesis or papers I am writing. It might also be that a user (you?) asks for access to the example files to translate them to another language. I certainly wouldn’t mind to give you access to the manuals’ example project. However, I wouldn’t give someone who wanted to look at the example files, and whom I don’t know, access to my PhD project. Hence, the example files for the manual are in a separate project, so I could share the project easily via Dropbox, independently from my PhD project.

If in doubt, manage everything in a single project rather than creating a project for every little piece of work, and keep in mind that it is not (yet) comfortably possible to use literature from one project in another project.

Why should I use a mind mapping tool to draft my documents?

Mind maps are suited perfectly for organizing your ideas and drafting your documents, since:

  • you can store the information hierarchically (instead of using a plain table or a list of nodes)
  • you can hide/show (un)necessary information really fast by collapsing or expanding any nodes.
  • you can outline your document by using 1st level nodes as chapters, 2nd level nodes as sections, …, and you can directly add both pdf annotations and your own ideas as leaves to the right place
  • you can change the structure of your drafted document really fast by dragging nodes (representing for instance a section) around and dropping them on another node

What has Docear to do with Freeplane?

Docear is based on the mind mapping software Freeplane. That means, we adopt the source code from Freeplane, extend it with further functionality e.g. regarding PDF and reference management, and build Docear from it.  That means, every change the Freeplane team is doing in Freeplane, is automatically available in Docear (as soon as we update to the latest Freeplane source code which happens every couple of months). This also means that when you have a feature request or bug report you may consider to submit it to the Freeplane team. This is particularly recommendable if the bug report or feature request related to a basic mind mapping function such as layout, printing, notes, links, etc. Anything related to the workspace, reference management, PDF management and the Docear online services definitely should be addressed to the Docear team.

PDF Viewers

Why is Docear showing a “The access to the file is blocked” warning?

To import new annotations, Docear needs write access to a PDF. Write access is needed because Docear writes unique IDs to each annotation in the PDF when the annotations are imported. This is necessary because some PDF readers occasionally overwrite the standard annotation IDs. However, most PDF viewers block write access for a PDF that is opened in that PDF viewer. Hence, when Docear wants to open a PDF and realizes that there is no write access, this dialog appears:

When this dialog appears, there is no other option than closing the PDF in your PDF viewer, or skipping the process of importing annotations for that PDF. Currently, this dialog always appears when a PDF is opened in your PDF viewer, even when you have not created any (new) annotations in the PDF file. We know that this is not ideal and plan to change this. This means, in one of the next versions, Docear won’t show the warning message if the PDF does not contain any new annotations (if there are new annotations in the PDF, such a warning dialog is inevitable) .

If this warning dialog annoys you too much, you might consider to use a PDF reader that does not block write access to PDFs. In this case, Docear could writes its own annotation IDs to a PDF although it is opened in a PDF viewer. However, we would not recommend this. If Docear changes annotation IDs while the PDF is opened in your PDF viewer, and you make some changes in your PDF viewer and save the PDF, Docear’s changes will be lost. This might result in unpredictable behaviour such as non-working links or a duplicate import of annotations in Docear. According to one user, a Windows PDF Reader that does not block writing access to PDFs is Foxit Reader 4.2 (or older). Please note that we will not provide support, if some of your data get lost because you used such an old PDF viewer!


Why is PDF-XChange Viewer or Adobe Acrobat Pro not recognized?

Sometimes, PDF-XChange Viewer is not recognized by Docear. There are three potential reasons.
  1. You did not install PDF-XChange Viewer. Please note that PDF-XChange viewer it not installed by Docear automatically. It needs to be installed by you.
  2. You did install the wrong PDF viewer. Tracker Software offers several PDF viewers with nearly the same name. Please make sure to download the free PDF-XChange viewer application. Other products, e.g. PDF X-Change editor, will not work!
  3. You downloaded the wrong download type. By default, a ZIP file is offered as download and there is also a portable version. Neither the ZIP nor the portable version will work with Docear. Docear can only recognize PDF-XChange viewer, when it is properly installed. This means, you need to download the EXE Installer.

It’s best to download the EXE Installer of PDF-XChange Viewer from TrackerSoftware’s download page because the product page is not well structured. Alternatively, you can directly download the correct file here: http://www.tracker-software.com/downloads/PDFXVwer.exe (download the file and then execute it).

If you downloaded and installed the correct version, and Docear still does not find the installation of the PDF X-Change viewer, please report this problem in our forum and answer the following questions to help us tracking down the issue:
  1. Which operation system with which architecture do you use? e.g.: Windows 7, 64-Bit
  2. Which version of Docear do you use? e.g.: stable build214 (You can find the version of Docear by clicking “Help” > “About” in Docear’s ribbon bar.
  3. Which version of the PDF X-Change viewer do you use? e.g.: 2.5 (Build 212.0)
  4. Which version of Java do you use? Please open the console and execute the command “java -version” in order to find out. On Windows 7 systems you can open the console by pressing the “Start”-Button and typing “cmd” in the small input field inside the menu.

If Adobe Acrobat Pro is not recognized by Docear, please try to start Docear as an Administrator.

PDF Management

Why does Metadata Retrieval (from Google Scholar) not work?

In the past weeks, some users have problems with retrieving metadata for their PDFs. The problem is that they either have to enter captchas, or they just do not get any metadata at all. If you experience the same problem, then Google Scholar probably identified you as a robot who sends too many requests to Google Scholar.  Unfortunately, there is no ultimate solution to this problem, but you may try the following:

  1. Delete the cookie that Google Scholar created. You find it here: /user_directory/users/<docear_username>/GoogleScholarCookie.xml
  2. Clear all Docear settings (and re-import your project(s)).
  3. Limit the amount of results being fetched from Google Scholar: For each PDF that you need metadata for, Docear sends four queries to Google Scholar. The first query sends e.g. the title of your PDF to Google Scholar. The other three queries are to fetch the BibTeX data from Google Scholar for the three first results. It might help, if you limit this so Docear requests BibTeX data only for the first result (this will lead to a total of two queries send to Google Scholar). You can change the number of results to fetch from Google Scholar, in the settings dialog:

  4. Open your web browser and open a “private” browsing session. In Chrome you do this by pressing CTRL+SHIFT+N, in Firefox and Internet Explorer you press CTRL+SHIFT+P. Then, visit http://scholar.google.com. The private session is important, don’t use a ‘normal’ browser window. Then, enter some search query and press the search button.

    Now, a captcha should appear:

    Enter the captcha, and if you are lucky you can now use metadata extraction in Docear again.

  5. Change your IP: If you are working from home, changing your IP should be easy in most cases: just restart your router. If you are at a university, you probably have a static IP. Ask your administrator whether there is any way to change it (probably not). Alternatively, you might use a Virtual Private Network (VPN) to connect to the internet.

Please, if you had difficulties in getting metadata from Google Scholar, let us know, which of the workarounds helped (or if you still have problems)


How to run Docear under MacOS 10.11 El Capitan (and Java 8)?

Several users reported problems with starting Docear under Mac OS El Capitan (10.11). One user found the following solution. Please let us know, if you found another way, or have some suggestions for changing the following tutorial.

  1. Download the latest Docear version.
  2. Follow the instructions on https://oliverdowling.com.au/2014/03/28/java-se-8-on-mac-os-x/
  3. Try to start Docear again. If it still does not run, try the following
    • Visit http://sourceforge.net/projects/freeplane/files/ and download  freeplane-1.5.2-alpha_pre01 or any later version
    • Replace framework.jar and freeplanelauncher.jar in your Docear directory with the files from your downloaded Freeplane version

Why is MacOS showing me “The file is damaged and should be moved to the trash.”?

If you have downloaded Docear as ZIP file and when unzipping the file you get the message “The file is damaged and should be moved to the trash.”, then please read on here http://www.statsilk.com/support/faq/resolving-mac-only-error-file-damaged-and-should-be-moved-trash

Migration from Other Reference Managers

How to resolve duplicated references?

As you may know, there is no real BibTeX standard but lots of different dialects and styles.

Zotero for instance creates BibTeX references with un-escaped semicolon or colon characters, although they are used to separate multiple files from each other and to separate meta information like the file’s description and the file type from the actual file path.

Warning dialog about duplicate references

You can now select that you want Docear to always ignore duplicate references. Instead of manually resolving them and leaving only one reference per PDF document or URL that Docear can find unambiguously, Docear will always use the first reference it finds in your Library. This means you don’t have to worry about duplicates in BibTeX files created by Mendeley. This also means that you might link different references in your mind map files, however, we think that this should not be a big problem, since the references are duplicates and hence should contain the same data.


How to migrate from Mendeley?

Migrating from Mendeley to Docear is easy (as long as you did not annotate your PDFs in Mendeley).

Migrating References

In Mendeley, first empty your trash. Then, open Mendeley’s preferences and activate “BibTeX syncing” as shown in the screenshot. Specify a path that is within your Docear project home. Then close Mendeley. Now, there should be a library.bib in the path you specified.

Mendeley BibTeX Settings

This library.bib is the file you can use in Docear. In Docear, open the workspace panel, and do a right click on the “References” entry. Chose “Change reference database” and select the library.bib. If you should experience any problems, please contact .

Migrating PDFs

In Docear, just add the folder in which your PDF files are, as new literature repository. This will allow Docear to import all your PDFs.

If you created annotations (highlighted text or notes) with Mendeley in your PDFs, then you have a problem. Mendeley is storing the annotations in a proprietary format and hence Docear cannot import them. The only option to access your annotations in Docear is to export each of your PDFs in Mendeley separately via the “Export PDF with annotations…” function.

However, even this function does not export your annotations in a 100% standard PDF format.  Your comments (pop-up notes) will be exported fine in general but for each comment, a non-removable field is added. In addition, the highlighted text is converted by Mendeley to a plain yellow area that is not recognized as highlighted text by other PDF readers and which hence cannot be imported by Docear (you cannot even delete the highlighted text). You can read more about this in our Blog (in particular in the comments). So, the only solution is to re-highlight all your text if you want to use it in Docear.


How to migrate from Citavi?

Sorry, we have no specific instructions on how to migrate from Citavi because no users have told us how to do it (and we don’t have Citavi installled). If you migrate from Citavi to Docear, we would very much appreciate if you could send us some instructions that we can publish here in the FAQ.

How to migrate from Endnote?

One of our users sent us the following instruction for migrating from Endnote. This procedure will capture all entries but not all fields.

1. Get the Bibtex style from the link below and double click on it while EndNote is running.

This style file is for exporting citations, not for exporting the database. There are many other fields within EndNote,  some of which have no mapping to BibTex fields!

2. In EndNote X7, go to Edit->Output Style->Open Style Manager, then check the Bibtex export and close the window.
3. Go to Edit->Output Style->and select BibteX Export.
4. Select the whole library or the references which you want and go to File->Export and : 1. Save as type= Text File(*.txt) 2. Output Style= Bibtex Export, then save it.
5. Go to the location of the saved text file and change the extension to *.bib and save it.
6. Now you need to configure Docear. Select your Endnote BibTeX file in Docear (right mouse click on References->change location in the left column and locate your bib file).
7. After selecting the BibTeX file, you need to tell Docear where EndNote saves your PDF files. First, open the “Change location” dialog in Docear (right mouse click on “Literature Repository”) (or add the EndNote repository as an additional literature repository). Note that EndNote repository is in the folder which you save your library. Inside this folder there is another folder which ends with “.Data”. Open it and select PDF folder. (Also, you can select the parent folder since Docear can read subfolders automatically. Important. Every time you insert a new reference in EndNote, you have to repeat the first 5 steps since EndNote doesn’t save bib automatically.

The above will not export the file links into the BibTex file giving direct access from JabRef as provided by the legacy PDF and PS directory configuration within JabRef. There can also be file links in Endnote to files outside the Endnote database that will not be captured by the above procedure.

How to migrate from RefWorks?

Sorry, we have no specific instructions on how to migrate from RefWorks because no users have told us how to do it (and we don’t have RefWorks installled). If you migrate from RefWorks to Docear, we would very much appreciate if you could send us some instructions that we can publish here in the FAQ.

How to migrate from JabRef?

Docear has integrated JabRef. This means, Docear offers most (but not all) of JabRefs functionality. All you need to do, do migrate is specifying your JabRef BibTeX file in Docear. Then, you will have all your data from JabRef also available in Docear’s reference panel.

How to migrate from other reference managers?

To migrate from other reference managers, you need to look whether your current tool has a BibTeX export. If you can export your data as BibTeX, you may specify the BibTeX file in Docear.

How to migrate from BibTeX based reference managers?

If you are using a reference manager that stores its references in BibTeX format, a migration is easy since Docear also uses the BibTeX format. All you need to do is specifying in Docear where your BibTeX file is stored. Then, Docear will show your data in its reference panel.

How to migrate from Zotero?

If you want to migrate from Zotero to Docear you need to export Zotero’s data as BibTeX file.

  1. Export Zotero’s references as shown on the screenshot to a BibTeX file. Save the BibTeX file in a location that will be part of your Docear project home, e.g. c:\university\zotero.bib. 
  2. Select your Zotero BibTeX file in Docear (right mouse click on “References”).
  3. After selecting the BibTeX file, you need to tell Docear where Zotero saves your PDF files.
    1. First, open the “Change location” dialog in Docear (right mouse click on “Literature Repository”) (or add the Zotero repository as additional literature repository)
    2. Select the folder in which your PDFs are. In Windows 7, the path looks like this
  4. To have a better overview in Docear we would recommend making the following setting (Monitoring – Settings – Flatten directories), but this is optional.

Zotero can export its data to BibTeX BUT for whatever reason Zotero does not export the file names and paths. Therefore, Docear cannot analyse which BibTeX key is assigned to a PDF. Potential workarounds are

  1. Visit Zotero’s forum and support our request to include file names and paths in the exported BibTeX file (just register and post a “me too”)
  2. Consider using Docear’s integrated reference manager instead of Zotero. There is a tutorial on how to switch from Zotero to JabRef. Since Docear uses JabRef, this tutorial should work for Docear users as well. Feel free to let us know your experience.
  3. Use Mendeley as converter. Download Mendeley, go to Tools | Options… and pick Zotero / CiteULike and select your Zotero database. Mendeley will then permanentely create a BibTeX file (of course you have to start Mendeley from time to time). Read here how to set up Mendeley to create a BibTeX file automatically.
  4. A user of Zotero has created a solution that should work exactly as we need it for Docear (start reading from the post from Mar 16th 2012). However, it requires quit a bit of work and at least for some users it does not work at all.

If you find a way how to switch from Endnote to BibTeX/Docear or using both in conjunction, please let us know.

Working with Docear and other reference managers at the same time

How to use Mendeley and Docear at the same time?

In principle, it’s possible to use both Docear and Mendeley with the same data. However, there are two problems, namely Mendeley’s slightly awkward BibTeX export, and their proprietary PDF format. If you want to use Mendeley, we suggest you have a look at why Mendeley might be considered a bad reference manager that will lock-you in. If you disagree, or don’t mind, and still want to use Docear and Mendeley, read on…

Using the same reference data

Mendeley has a feature to create and update a BibTeX file that can be used with Docear. To activate this function in Mendeley, select “Tools -> Options -> BibTeX” and ensure all settings are as in the screenshot. The Path is not fundamentally important but ideally it should be within the project home of Docear.

Mendeley BibTeX Settings 

To tell Docear where your Mendeley-BibTeX file is stored, do a right click in the workspace panel on the “References” database and chose “Change reference database”. Then select your Mendeley BibTeX file (it is called library.bib and it is stored in the path you specified above).

Important: Do any changes on your reference data directly in Mendeley. Do not change reference data in Docear because all changes made in Docear will be overwritten by Mendeley. If you like, visit the Mendeley support forum and vote on the idea that Mendeley synchronizes BibTeX data in both  directions.  

Resolving duplicate BibTeX entries

If you export a BibTeX file from Mendeley the exported file will probably have a lot of duplicated entries. The Mendeley team knows about this issue since April 2010, but they have not changed it yet. Docear depends on unique references and in general it does not make any sense to have any duplicates in a BibTeX file, so please vote to fix it. Until they have fixed it you can work around this bug by emptying your trash in Mendeley before exporting your reference database to a BibTeX file. If this does not help and you still get duplication warnings in Docear, please send your BibTeX file to  along with a comment what went wrong and we will try to find the error and fix it for you. Also, Mendeley does not include entries set to “Details need review”. Please vote here  to have Mendeley include all entries in their BibTeX export.

Using the same PDF files

We highly recommend to deactivate the functions “Sort files into subfolders” and “rename document files” because otherwise problems might occur in Docear when files are automatically renamed by Mendeley (Docear won’t find them when Mendeley renames them).

Mendeley File Organizer

If you have activated the function “Organize my files” in Mendeley, it is important to specify the directory that you specified in Mendeley also as your literature repository in Docear. Only then, Docear and Mendeley can work with the same PDF files. To do so, do a right click on “literature repository” in the workspace panel and select “Add Literature repository”. Select the same directory you have specified in Mendeley.

If you do not have activated the function “Organize my files” in Mendeley, you need add the folder you are watching in Mendeley as literature repository in Docear. You find this folder in Mendeley in the Options in the tab “Watched Folders”.

Mendeley Watch Folder

Finally, you should be aware that Mendeley is not using the standard PDF format for storing annotations in PDFs. This means, when you create annotations in Mendeley, Docear cannot access them (nor can any other normal PDF editor). Therefore, we strongly suggest that you create and manage your annotations only with Docear and your favorite PDF viewer but not with Mendeley. 


Why is Docear not recognizing Zotero’s BibTeX file, or producing exceptions?

Some users occasionally report that Docear has problems with recognizing the BibTeX file that they exported from Zotero (or from one of Zotero’s add-ons). Sometimes, the reason is that Zotero (or the add-ons) produce invalid BibTeX code. For instance, sometimes, closing brackets ‘}’ or commas ‘,’ are missing. Here is, how a valid entry should look like (we highlighted some pairs of opening and closing brackets, and commas):

Currently, Docear does not tell you were in the BibTeX file an error occurs but just ignores the BibTeX file (we are planning to implement a more informative error message). Therefore, to check your BibTeX file for validity, do one of the following options:

  1. Locate the problem in the BibTeX file
    1. Open your BibTeX file with JabRef (you don’t have to install JabRef, you could just use the WebStart version). If your BibTeX file is not valid, you will get an error message like this:
    2. Alternatively, open your BibTeX file with Docear4Word. To do so, specify your BibTeX file in the settings.
      Then, Docear4Word will tell you at which line the error occurs.
  2. Fix the error: Open the BibTeX file with a text editor (e.g. Notepad), go to the line with the problematic code, and fix it. If you want us to fix the problem, please read here. However, the problem most likely will always re-occur when you freshly export your Zotero data to BibTeX. A workaround might be that you delete the problematic entry from Zotero’s database. You probably don’t have to delete the entire entry but only the problematic field (e.g. the abstract).

In other cases, Docear itself causes the problem. Because Zotero’s BibTeX format is not 100% compatible with Docear’s BibTeX format, Docear does some parsing and changes some minor formatting of the BibTeX file. However, in some situations, this may lead to errors. We are not 100% sure when the errors occur but the problem most likely relates to line breaks in your Zotero annotations. For instance, if you have an annotation in Zotero that looks like this when exported to BibTeX…

annote = {{Docear} is
an academic literature suite
download it at www.docear.org.

… then Docear will parse the BibTeX file incorrectly. To fix the problem, remove the line breaks directly in Zotero and re-export your data.  Please note that we are planning for a more robust BibTeX handling.

How to use Zotero and Docear at the same time?

If you want to use Zotero together with Docear you need to export a BibTeX file, each time you change or add an entry in Zotero. This process can be done automatically with the Zotero plugins “AutoZotBib” and “Zotero Autoexport“.

If you don’t want to use these plugins you can export the BibTeX file manually by following these steps (you have to do it each time you make changes in Zotero):

  1. Export Zotero’s references as shown on the screenshot to a BibTeX file. Save the BibTeX file in a location that will be part of your Docear project home, e.g. c:\university\zotero.bib. 
  2. Select your Zotero BibTeX file in Docear (right mouse click on “References”).
  3. After selecting the BibTeX file, you need to tell Docear where Zotero saves your PDF files.
    1. First, open the “Change location” dialog in Docear (right mouse click on “Literature Repository”)
    2. Select the folder in which your PDFs are. In Windows 7, the path looks like this
  4. To have a better overview in Docear we would recommend making the following setting (Monitoring – Settings – Flatten directories), but this is optional.

There are many more add-ons for Zotero that facilitate BibTeX export etc. For an excellent overview, read here.


Why am I being blocked and can’t log-in or comment?

We are using various Anti-Spam Add-Ons to prevent spammers flooding our Blog and forum with spam. If you are blocked and can’t comment, log-in, post or what so ever, please send an email to help @ docear.org and tell us what exactly you did and what your IP is. We will set your UIP on a whitelist then.

What to do if I forgot my password and/or username?

Passwords in our database are all encrypted. Therefore, there is no way to retrieve your old password but you can try this: Look in your email archive for an email from with the subject “Docear Account Signup Confirmation”. It includes your username and the last three characters of your password. If you don’t have this email any more, or if the last three characters don’t help, reset your password.

Other Mind Mapping Tools

Freeplane vs. Docear — what are the differences?

Sometimes users ask us whether they should use Docear or Freeplane, and what exactly the differences are. Well, Docear is based on Freeplane, extended by some additional functionality. Namely, we added some special PDF management capabilities (import of PDF annotations), reference management (based on JabRef), the workspace concept, and some online features such as backup. Although, the latter two features (workspace and backup) soon will be available in Freeplane, too. That means Docear can do everything Freeplane can do, and a little bit more. This might sound like you should always use Docear but that is not true. There are some good reasons (for some people) to use Freeplane. Namely, if you don’t need Docear’s special features we recommend using Freeplane. This gives you three advantages. First, you don’t get annoyed by features you don’t need. Second, and more importantly, the start-up of Docear is very slow because we start all the program code from Freeplane plus JabRef (reference management) plus the other features. That means, Freeplane is much faster. Third, the Freeplane team is highly active and releases new versions of Freeplane very often. We update to Freeplane’s source code once in a while which means with Docear you might not always have the latest bug fixes which are already included in the latest Freeplane version.

In short: if you need Docear’s features, use Docear. If you don’t need Docear’s features, use Freeplane because it’s faster and usually contains less bugs.


How can I cope with huge mind-maps, and e.g. work on several parts at the same time?

If you are working with huge mind-maps, you might want to open different parts of this mind-map and e.g. move nodes from one part to another part, without navigating through the mind-map all the time. To do this, it would be perfect, if you could open the same mind-map in two windows, having each window showing a different part of your map, and then you could drag&drop some nodes from one window to another. Unfortunately, this is not yet possible. However, maybe one of the following suggestions helps you

  1. Work with two instances of Docear and a temporary mind-map
    1. Open your mind-map in Docear
    2. Create a new mind-map, e.g. temp.mm
    3. Open temp.mm in a second instance of Docear
    4. Cut one part of your original mind-map and paste it in temp.mm
    5. Arrange your two Docear instances on your monitor, and cut and paste nodes from your temp.mm to the original mind-map
    6. Alternatively, open multiple mind-maps in one instance and switch between them (read here for more details)
  2. Use Freeplane 1.3 (or later)
    1. Download Freeplane, which uses the same file format as Docear.
    2. Since version 1.3, Freeplane has an enhanced window mode that allows showing multiple mind-maps in the same instance of Freeplane (see screenshot). In the long run, we will also integrate this into Docear, but until then, you might want to use Freeplane for working in large mind-maps (you don’t have reference management, workspace, etc. in Freeplane)
    3. The way you would work with Freeplane is the same as explained previously.  Create a temporary mind-map, and copy/move parts from your original mind-map to it.
    4. The Freeplane team is also very open to suggestions. So, if you want to ask them to improve anything of the multi-window mode, just go ahead.
  3. Get used to Docear’s keyboard shortcuts and make use of the folding options
    Docear has a lot of useful keyboard shortcuts to navigate through mind-maps and quickly fold (hide) and unfold (show) nodes. Have a look at the “Nodes” options in the “Navigation” tab of the ribbon menu. With these options it is rather easy to display only those parts of a huge mind-maps that you really need.  The below screenshot shows an example, for more information read here.
  4. Buy a larger monitor
    If you think that you will use Docear for the next couple of months or even years to manage your literature, then you should seriously consider to buy a monitor as large as you can afford. For Docear, and mind-mapping in general, you screen can’t be large enough. Actually, most members of the Docear team use 27″ or 30″ screens and this is definitely not too large. We can promise that if you are currently using a small screen (e.g. a 15″ laptop monitor), and you switch to a larger screen, e.g. 24″ you will be blown away by how much easier it is to work with Docear.

If all these steps don’t help, read on here how to enhance your productivity with Docear.

How can I change/add keyboard-shortcuts?

It is very easy to add or change a keyboard shortcut. Simply find the function you want a keyboard shortcut in the menu, hold the CTRL key on your keyboard and click on the entry in the menu. A dialog will open that allows you to specify the keyboard shortcut. That’s it :-).


How can I create references in footnotes or text-fields?

Sorry, currently, you cannot create references in footnotes or text-fields. We know, this is annoying and we hope that we can fix this problem soon, but it might take a while.

How can I localize strings like “p.”, “pp.”, “et al.”, … ?

If you are writing a non-english article, you might not want page numbers abbreviated by “p” or “pp” but in your particular language. Or you might “et al.” in another language. You can change these strings in your Sys.js file which is located in c:\Program Files (x86)\Docear4Word\JavaScript\. In that file search for the string you want to change, change it, and save the file.

Why can Docear4Word not load my BibTeX file (Unexpected error at line x, column y)?

If you try to add a reference in MS-Word, and your BibTeX file is invalid, you will receive an error message like this:

If you receive such an error message, there are three potential solutions

1. Install the latest Docear4Word version

2. Fix the problem yourself

To fix the problem, open your BibTeX file with a text editor, e.g. Notepad and go to the line with the erroneous entry (the error message contains the line number, e.g. 4)

If you have an error in a large BibTeX file at e.g. line 1312, and you don’t want to count the lines manually, activate the status bar in Notepad. This will display the line and column of your cursor in the bottom right corner.

Alternatively, install a text editor like NotePad++, which displays the lines by default.

There are two reasons that lead to corrupt BibTeX files.

A) Invalid BibTeX keys

Each reference has a unique BibTeX key, i.e. the string after e.g. @ARTICLE{. Certain characters are not allowed as BibTeX key. These characters are # & / \ ‘ : ? < > (and maybe some others). If you see such a character, delete it, save your BibTeX file, and everything should work fine again (unless you have more entries with invalid characters, but Docear4Word will tell you). If you are using Mendeley, you should change the BibTeX key (citation key) directly in Mendeley, and not in the BibTeX file.


B) Missing brackets

Each entry in your BibTeX file has a number of attributes (e.g. author, title, journal name, pages, …) and the value of each attribute is enclosed by {  }. If such a bracket is missing, Docear4Word cannot read the file.

This is how a correct entry looks like

This entry would be corrupt (a closing bracket is missing at line 6789).

If you find such an error, add the enclosing brackets at the correct positions (and don’t forget a comma after the bracket if it’s not the last attribute), save the file and that’s it. If you have used a reference manager other than Docear (e.g. Zotero or Mendeley), and this reference manager exported an incorrect BibTeX file, please contact the developers and ask them to fix this bug (it’s definitely a bug if some entries are created without enclosing brackets).

3. Let us fix the problem

If you have tried all the previous steps but failed, we might fix the file for you.

Why does “Creating Citation…” appear when I want to add a reference?

If you add a new reference in your Word document and receive the message “Creating Citation…” (see image below), there are three potential reasons.

1. You tried to add a reference at an invalid location. For instance, Docear4Word cannot insert references in footnotes or text-fields. If you try to do, the message “Creating Citation…” will appear. We know, this is annoying, and we are planning to fix it, but we cannot yet say when this will have enough time for this. For now, the only solution is to not add a reference in a footnote or text-field, or to add it manually, i.e. to just write the string such as [1] or Smith (2012) manually.

2. You activated “track changes” in MS Word. In this case, Docear cannot add new references and the “Creating Citation…” message appears. We plan to fix this issue, but we cannot tell you when this will be. Meanwhile, the best workaround is to accept all changes in MS Word, and then to add the reference. Alternatively, open a new document, add the reference in that document, and then copy the reference to your working document. It might be that the numbering of the references is not correct, and the reference is not added to your bibliography. To correct this, click the Docear4Word “refresh” icon after you are done with your work and accepted all changes.

3.  The problem might also be caused by a corrupted reference. Docear4Word adds reference data such as author, title, etc. as invisible field codes to your document. If this reference data is modified for whatever reason, the reference becomes corrupted and Docear4Word might have troubles to add further references, which results in the “Creating Citation…” error. The below picture illustrates the problem: If you do a right mouse click on a reference and select “Toggle Field Codes”, you will see the exact code that Docear4Word added to your document (do a right mouse click on the code and select “Toggle Field Codes” to switch back to the “normal” view).

Assuming that some field code of a reference has been changed, there is only one solution: You need to find the corrupted reference, delete it, and add the reference again. This can only be accomplished by a systematic trial-and-error search. We would suggest one of the following two options to find the corrputed reference

Option i)

  1. Create a backup of your document
  2. Open your document in MS Word, ensure that the cursor is at the beginning of your document
  3. Click the “Next” button in Docear4Word (this will select your first/next reference in the text)
  4.  Click the “Edit Reference” button.
  5.  If the normal dialog appears to add/edit references, your currently selected reference is ok. Repeat steps c. and d. until the following error message appears.
  6.  The message indicates that something is wrong with the reference. Hence, you need to replace it. In the dialog, click “No”. Then, remove the reference from the text.
  7. Try to add a new reference. If still the message “Creating Citation…” appears, there are more corrupt references. Identify them as described, delete them all and when you deleted them all, you can add the references again.

Option ii)

  1. Create a copy of your document
  2. Open that copy in MS Word
  3. Select about half your text (e.g. all text including images, tables, etc., on pages 1-23 if your document contains 46 pages)
  4. Cut the text (CTRL+X)
  5. Try to add a reference
  6. If you still receive the error, start again with c. (select half your remaining text, cut it, until you can add a reference)
  7. If you can add a reference, this means that the corrupted reference was in the text that you just cut. Continue with h.
  8. Select all the remaining text in your document and delete it (you don’t need it any more for the coming analysis because it only contains valid references).
  9. Paste (CTRL+V) the text that you previously cut, so it’s back in your document (and contains the corrupted reference)
  10. Again select half your text and cut it, until you can add a reference, paste the remaining text back to your document, etc. and repeat the process until you have only a single reference left in your text
  11. This single reference is the corrupted one.
  12. Open your original document, find the location were the corrupted reference is, delete it, and re-add it with the “Add Reference” icon in Docear4Word.
  13. Now, everything should be fine

If none of the proposed solution works, please send us your BibTeX file and your MS Word document (either the original, or an example file) to .


Help us solving this problem: Unfortunately, we have no idea why this problem occasionally occurs. Hence, if you can reproduce the steps that lead to a corrupt reference, please let us know, so we can fix the problem.

Why are spaces removed in the bibliography?

Docear currently has a bug that removes spaces and prepositions:


To fix this bug, download our modified citeproc.js file and overwrite the existing file, usually located in C:\Program Files (x86)\Docear4Word\JavaScript\

Why is the order/numbering of citations not correct?

Users often ask why citations are numbered e.g. … [1] … [3] … [2]  and not … [1] … [2] … [3] . The answer is easy: because of the citation style you use. Some (but not all) citation styles order the entries in the bibliography by the authors’ last name. In the example, a bibliography might look like this

[1]    Agarwal, N. et al. 2005. Research Paper Recommender Systems: A Subspace Clustering Approach. Proceedings of the 6th international conference on Advances in Web-Age Information Management (WAIM’05) (2005), 475–491.

[2]    Burke, R. 2002. Hybrid recommender systems: Survey and experiments. User modeling and user-adapted interaction. 12, (2002), 331–370.

[3]    Castells, P. et al. 2009. Novelty and Diversity Metrics for Recommender Systems: Choice, Discovery and Relevance. Proceedings of International Workshop on Diversity in Document Retrieval (DDR) (2009), 29–37.

The list is ordered alphabetically. Therefore, if you cite the paper by Burke first in your paper, it will be numbered [2]. If you want your citations numbered by the order they appear in the full-text, you must select another citation style that supports this (e.g. the IEEE style).

There is another issue some users experience. When you cite two references at once, they might appear as [2,1], though it should be [1,2]. If this happens, your citation style was not written properly. In this case you can edit it with a text editor locally, or, ideally you fix the citation style online so other users can benefit from the change. To fix the sorting issue, add a

   <key variable=”citation-number” sort=”ascending”/> 


after the command <citation collapse…> and before the command <layout…>.

If this also does not help, please send an example Word document and your BibTeX file to .

How can I keep two (or more) words as last name?

Sometimes, (last) names consist of multiple words and you don’t want a reference to show only one of that words as last name. For instance, when you want to cite “Microsoft Research”, you don’t want only the term “Research” to appear as name but “Microsoft Research” instead.

Multiple authors with “normal” names

If a document was created by multiple authors, you can separate them with the term “and” in the author field of Docear. For each author, the last word is always assumed to be the last name and all other words are assumed to be first or middle names. Here are some examples of multiple authors with “normal” names, i.e. one first and one last name (and one middle name).

Input in Docear BibTeX Code in Docear In-text citation in MS-Word Bibliography in MS-Word
Peter South and Sandra Young author = {Peter South and Sandra Young}, (South and Young, 2000) South, P., Young, S., 2000. …
Peter Adam South and Sandra Maria Young author = {Peter Adam South and Sandra Maria Young}, (South and Young, 2002) South, P.A., Young, S.M., 2002. …

Double names

If an author has a last name consisting of two or more words, the above procedure will not deliver satisfying results (see first row of the below table). Instead, you need to separate the last and first names with a comma and write the last name first.

Input in Docear BibTeX Code in Docear In-text citation in MS-Word Bibliography in MS-Word Note
Clara Linda Miller Brown and Tina Maria Backer White author = {Clara Linda Miller Brown and Tina Maria Backer White}, (Brown and White, 1975) Brown, C.L.M., White, T.M.B., 1975. … Incorrect
Miller Brown, Clara Linda and Backer White, Tina Maria author = {Miller Brown, Clara Linda and Backer White, Tina Maria}, (Miller Brown and Backer White, 1977) Miller Brown, C.L., Backer White, T.M., 1977. … Correct

Suffixes (Jr., Sr., …)

If an author has a suffix like junior (Jr.) or senior (Sr.), you need to enter this name as lastname, firstname (middlename), suffix, (don’t forget a comma after the suffix).

Input in Docear BibTeX Code in Docear In-text citation in MS-Word Bibliography in MS-Word Note
Walter White, Jr. and Walter White, Sr. author = {Walter White, Jr. and Walter White, Sr.}, (Walter White and Walter White, 2012) Walter White, J., Walter White, S., 2012. … Incorrect
Walter White, Jr., and Walter White, Sr., author = {Walter White, Jr., and Walter White, Sr.,}, (Walter White and Walter White, 2012) Walter White, Jr., Walter White, Sr., 2012. …  Incorrect
White, Walter, Jr., and White, Walter, Sr., author = {White, Walter, Jr., and White, Walter, Sr.,}, (White and White, 2012) White, Walter Jr., White, Walter Sr., 2012a. … Correct

Company names

Input in Docear BibTeX Code in Docear In-text citation in MS-Word Bibliography in MS-Word Note
Microsoft Research and Google Inc. author = {Microsoft Research and Google Inc.}, (Research and Inc., 2014) Research, M., Inc., G., 2014. … Incorrect
Microsoft Research, and Google Inc., author = {Microsoft Research, and Google Inc.,}, (Microsoft Research and Google Inc., 2014) Microsoft Research, Google Inc., 2014. … Correct
\{Microsoft~Research\} and \{Google~Inc.\} author = {\{Microsoft~Research\} and \{Google~Inc.\}}, (Microsoft Research and Google Inc., 2014) Microsoft Research, Google Inc., 2014. … Correct
{Microsoft Research} and {Google Inc.} author = {{Microsoft Research} and {Google Inc.}}, (Microsoft Research and Google Inc., 2014) Microsoft Research, Google Inc., 2014. … Not yet possible (coming soon)


How do I upgrade to the latest citeproc-js version?

Docear4Word is using citeproc-js which is responsible for the formatting of the references. Sometimes there are new releases of citeproc-js that fix some bugs or ad some new features. You can either wait a few weeks until we integrated the latest citeproc-js version into Docear4Word or upgrade manually. To upgrade manually, replace c:\Program Files (X86)\Docear4Word\JavaScript\citeproc.js with the latest version which you can download here.