FAQ FAILED: Could not find path to Sandcastle tools

Topics: Developer Forum
Sep 22, 2008 at 2:50 PM
Yes, it's an FAQ.  And yes, I'm posting about it anyway.
          Why does the build fail telling me that it cannot find the Sandcastle or HTML help compiler tools?
First and foremost, be sure that you have installed the latest version of Sandcastle and the HTML help compiler(s). The help file builder is not Sandcastle.
Then ofurgod's sake, why do you call the download, title the page, and the links "SANDCASTLE HELP FILE BUILDER" if that's not what it is?  What do I need to install now?  A help compiler or a help builder?  What's it called?

First, clean up the language a bit:

First and foremost, be sure that you have installed the latest version of Sandcastle and the HTML help compiler(s).  The help compiler is not part of Sandcastle.  The help compiler is part of the VS 2xxx Help Integration Toolkit available (see Links to Resources).
The download page for some multi-vendor projects is helpful in this respect.  On the DOWNLOAD PAGE ITSELF they'll have a ticklist of things to do:

  • Download the latest version of FooBar here.
  • You will need also one of the following:
    • MS FooBar Dev Toolkit available here.
    • Joe Blow's Open Source replacement for MS FooBar Dev
Since Sandcastle's "Build Failed" message doesn't tell me what it's looking for (Tools?  WTF are tools?  What are they called?  Which one?), the two threads in here unhelpfully don't either, and the FAQ points me to a list of things that -- if I install them all -- still don't solve the problem, I'll just uninstall Sandcastle and blow a few days writing an XSLT application.

Sep 22, 2008 at 3:35 PM
Edited Sep 22, 2008 at 3:36 PM
From the Getting Started section in the help file in the topic An Overview of the Help File Builder GUI:


In order to use the Sandcastle Help File Builder, you will need the following:
  • The .NET 2.0 Framework.
  • The latest version of Sandcastle (currently the June 2008 release when this was released). Note that this is a tool created by Microsoft. The help file builder uses it to produce the help file.
  • The HTML Help Workshop for building HTML Help 1.x (.CHM) help files.
  • The HTML Help 2.x compiler for building HTML Help 2.x (.HxS) help files.
See the Links to Resources help topic for information on how to obtain the above items and for references to other helpful information.


There is a list of links to the tools at the bottom of the project home page.  I'll add the above info to it as well to make it clear.  I'll also reword the build failure message to make it more clear as to what it is looking for.

Sep 22, 2008 at 3:38 PM
Having downloaded and installed all of this and still getting the message, I'll just have to wait until the build message is updated to find the problem.

Sep 22, 2008 at 7:26 PM
Well, if it says it can't find the Sandcastle tools that means one of two things:  Either you haven't installed Sandcastle, the one from Microsoft that the help file builder automates (http://www.codeplex.com/Sandcastle) or it can't find it via the DXROOT environment variable or the system path.  It is usually found in C:\Program Files\Sandcastle and there is a system environment variable called DXROOT that points to that location.  If SHFB can't find ProductionTools\MRefBuilder.exe in the Sandcastle installation folder, that's when you get that message.

Also note that if you've installed the VS 2005/2008 SDK, it can create a user copy of DXROOT and/or point it at the wrong location containing an outdated version of the tools.  If there's a user copy of the environment variable, delete it and make sure the system copy points to the place you installed the June 2008 release of Sandcastle (the one from Microsoft).