Quick tips for troubleshooting plugins in an Eclipse help system

The Eclipse help system is an extremely valuable tool that seems to intimidate new users.   This post is intended to cover some of the very basics about how to troubleshoot your plugins in an Eclipse help system.

Some basics first:

  • A plugin is a folder or JAR file that provides instructions to Eclipse for how to process.
  • Those instructions are given in the plugin.xml (extensions) and in the manifest file (prereqs, dependencies, etc).

Ensure the plugins are in the correct directory

While that might sound obvious, I have seen forum posts where the distinction between the workspace and plugins directories were causing problems. The workspace can be considered the directory where your source projects are stored for editing. That location is not processed by the Eclipse framework. You need to ensure that you store your plugins in the eclipse/plugins folder and in the correct format.

After you’ve checked that your plugins are in the correct location, verify that the contain the necessary files.

Plugins are formatted correctly and contain manifest/plugin.xml files

Open up your eclipse/plugins/my.plugin.folderorjar and check to ensure the plugin.xml is in the root of that folder or archive. You might optionally also have a META-INF/manifest.mf file.

Determine if Eclipse is picking up your plugin

Launch your help system or infocenter. If you are launching the help (Help->Help contents), you will want to open it with an external browser rather than the built-in browser. You can either change your preferences or you can just copy a TOC link address and paste it into a different browser. The port that the webserver for the Eclipse help system changes with each restart so you’ll need to determine that:

Your help URL will probably look something like…. Once you have that, change the URL to

If you get a topic not found or broken link

Then Eclipse did not pick up your plugin, which means something is likely wrong with your plugin.xml or manifest.

This could be a malformed XML file due to an XML markup error in your plugin.xml. Check that all tags are closed (</myclosetag>). Also, check for character encoding problems. XML is pretty strict when it comes to special characters and the most common problematic character is the ampersand (&). The ampersand in XML or XHTML (especially in links) should be represented in the file as: &amp;

Also, check that you are using the correct URL for your plugin. Eclipse uses the plugin ID in the path rather than the folder name or JAR file name.

If your plugin.xml file displays correctly

Then Eclipse found and registered your plugin. If this does not solve your problem, I am guessing you are wondering why your contents do not show up in the navigation. For your navigation file to be picked up, you have to register the TOC XML  file with the Eclipse org.eclipse.help.toc extension point in the plugin.xml.

If you want your toc to appear as a first level container, then you need to set primary=”true” for that TOC file:

<extension point=”org.eclipse.help.toc”>
<toc file=”toc.xml” primary=”true” />

If you want this TOC file to be a child to another TOC, then you would set primary=”false” and link the maps together using a link_to (navref in Dita source) element or anchor/anchor_to (anchor & anchorref in Dita source).

You updated a plugin and the changes are not displayed

This is likely due to caching that Eclipse performs. You can either start Eclipse with the -clean parameter passed to the executable or you can manually clean the cache.

To manually clean the cache: stop Eclipse, find your Eclipse installation directory. Within the configuration subfolder, delete all of the contents except for the config.ini file and the org.eclipse.update directory.

Other issues?

Post your Eclipse help issues  as a comment and I’ll try to address them here also.

8 thoughts on “Quick tips for troubleshooting plugins in an Eclipse help system

  1. My Eclipse help window is partly broken. The contents frame is empty, and all the icons across the top (Back, Forward, etc) show as red X’s. It worked when I first installed Eclipse (for Enterprise dev). I have version 3.5.2 of the Eclipse Platform, which comes with version 1.1.2 of the Help System Base, and this is on Vista with JDK 1.6.0_18. I’m guessing the internal help-system web server has somehow lost its images and JSPs. The plugins directory does have several org.eclipse.help.*.jar files, including org.eclipse.help.webapp_3.4.1.v20091009_35x.jar, which seems to contain the needed JPSs.

    Do you have an ideas? Thanks in advance.

  2. Hi Franz,

    I’ve seen the same issue before and can’t quite recall right now what was happening.

    What does the log file show? Should be in your workspace/.metadata/.log

    My guess is that either something is wrong with your launch configuration eclipse/configuration/config.ini or maybe your Eclipse was partially upgraded?

    You might also try switching workspaces to see if its something going on with your existing workspace.

  3. Thanks for the response. I cleared my .log file, restarted Eclipse, and showed the Help window. Nothing was written to the .log file. Also, I started Eclipse in an old workspace I haven’t used in a year. The Help window is the same there, half broken.

    I installed this version of Eclipse fairly recently, and I think the Help window initially worked. I don’t use it often, so I don’t know when it changed.

    As for JSPs, there definitely are some in eclipse/plugins/org.eclipse.help.webapp_3.4.1.v20091009_35x.jar, in the “advanced” and “basic” folders. Perhaps they just don’t get used for anything.

  4. I am also using Eclipse 3.5 on one of my machines. Here are the plugins and versions that exist in my system:


    You might try using Neil Bartlett’s bundle-monitor to see the status of these plugins to see if one of them isn’t starting for some reason. Might be able to isolate which is the issue.

  5. Hi Brett,
    Does IBM still offer the Eclipse help system as a download? I still have the version I downloaded a couple of years ago, but the link to the download site no longer works.


  6. Hey Bob!

    Long time. Was actually just talking about you today with some of our writers and I realized its been quite a while since you were at IBM. The IBM version of the Eclipse help system is now known as “IBM User Interface Help System built on Eclipse”. This site does not seem to be maintained anymore but I don’t think there is much now that the Eclipse help system offers that IBM’s offering doesn’t.

    The harder part is tracking down the Eclipse package that contains ONLY the necessary plugins and binaries for just the help system. You need what is known as the Eclipse Platform Runtime binary. For example, the Eclipse Help System version 3.4 is found at http://archive.eclipse.org/eclipse/downloads/drops/R-3.4.1-200809111700/index.php#PlatformRuntime. If you’re trying to run a standalone information center, you will want to look at the Eclipse Inocenter docs.

    What are you up to these days B1b? I heard the Shakespeare went well again this year.


  7. Hi Brett,
    Yes, I left IBM over 2 years ago now. I saw Tim Hogan and family in Monterey over the weekend, and we were talking about you, too….

    I was glad to find your site because I’m trying to reinvent the IBM approach to Information Centers in my job here. I wasn’t sure if I could get a Help-system-only version of Eclipse from Eclipse itself, but you answered that question before I asked it. I’ll take a look.

    We are using DITA in XMetaL and producing PDF only at this point, but I have a prototype Eclipse help system running on a Linux box. XMetaL is a bit like the ID Workbench but not as good in many ways. I’m looking at moving to Madcap Flare in the future, but they don’t have native DITA support yet.

    Anyway, thanks for the info. Yes, the Shakespeare group continues to grow and I am beginning to miss my IBM vacation. One of the perils of joining a startup….

    Thanks again,

  8. Hi Brett:
    I wonder if the following is possible. I have a project where I need to provide very specific Help files; the project is to supply OO Concept analogies to novice programmers. Ideally, what I would like is to have a menu item on the toolbar (something like OO Analogies) which would open a 2nd copy of the Help system structure – but without the current Help system contents. I would then supply the appropriate HTML files to populate the 2nd copy of the Help system structure. I have tried experimenting with the TOC but that just gives me the entire Help contents as they currently stand. I am looking for a standalone (and empty) Help System Structure that I can use, but that doesn’t break the standard Help system files. Not sure is that makes sense. If you had any thoughts on the matter I would appreciate it.


Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>