title: FXML / FXMLLoader error diagnostic tool(s) sought
body: <h2>overview</h2>
  
  <p>Hi, here's an <strong>outline</strong> use-case.  I have a seemingly valid FXML file developed in <strong>JavaFX Scene Builder</strong>.  It is by now a non-trivial chunk of XML and there are runtime load errors somewhere in the FXML file.  Scene Builder works fine with the Preview option.  I have a '<em>simple</em>.fxml' file I use to verify that the controller is working as intended, that is same controls and events but without the extra FXML layouts.  And I have and I am doing the cut-out-code and test loop to identify the XML with the problem.  So I will get to the bottom of this at some point.  </p>
  
  <p>At present there are no errors showing in Scene Builder nor in the Netbeans FXML editor and I don't get an error with the load as in "<a href="https://stackoverflow.com/questions/20661209/javafx-loading-fxml-file-error">JavaFX - loading FXML file error</a>"(#1).  All I get is an exception on end task in runnable, which says the loader threw an exception.</p>
  
  <h2>goal(s)</h2>
  
  <p>These errors happen.  The question is what tools are available or under development to <strong><em>Troubleshoot FXML files</em></strong>?</p>
  
  <p>Some thoughts, questions or options:</p>
  
  <ol>
  <li>Is this a bug?  To mind mind something as black box as a loader ought to issue some kind of indicator like failure on line 246 or " ... Something that indicates where to look.</li>
  <li>What tricks, techniques or suggestions do you have for ways to find /resolve such errors faster?
  
  <ul>
  <li>Is there a place for using Include</li>
  </ul></li>
  <li>What hooks are there on FXMLLoader class to catch or trap errors before it all falls-down?  </li>
  <li>Are there any facilities to log or diagnose the FXMLLoader processing?</li>
  <li>Has anyone written a custom FXMLLoader that could be used this way? (see #3).
  
  <ul>
  <li>I saw that FXML uses SAX, is it possible to wrap or hook the parser and give the FXMLLoader an alternate parser?</li>
  </ul></li>
  <li>Are there any static tools for analysing the FXML and Java application -- Like an <em>FXML Lint</em> or something?</li>
  <li>What indepth FXML load, parse, runtime information is available on how the FXML is processed.</li>
  <li>Are there or could some extra entry points be added-to or injected into the controller(s) to capture FXML load problems?
  
  <ul>
  <li>For example, can controllers be cascaded such that I can make a 'root controller' which might capture problems closer to the point of origin.</li>
  </ul></li>
  </ol>
  
  <p>At present problems inside the FXML that are only uncovered at the time of loading are just time-consuming and unpredictable if the editors don't see anything.  I'd like to see some diagnostic tools if anyone h</p>
  
  <h2>Further Insights</h2>
  
  <p>These are some relevant '<em>debugging</em>' and '<em>troubleshooting</em>' tips that come along during development.  Perhaps some of these may find their way into a FXML Validator or Lint tool one day(?)  The points are in no particular order, they are numbered for cross-reference purposes.</p>
  
  <ol>
  <li>Any controller identifiers in the FXML <strong><em>must be</em></strong> present and annotated in the Java code with @FXML.  If an annotation is missing the FXML won't load.  </li>
  <li>Every Java name annotated with @FXML should be in the FXML mark-up file.  Say a label called, "myLabel": if the myLabel used in the code there will be a NullPointerException.  The file will load, unlike case #1.</li>
  <li>Don't use the NetBeans "Compile on Save" compile option with JavaFX.  It seem to generate spurious NullPointerException-s on seemingly correct code.  </li>
  <li>If you rename/refactor your main app ensure you update the build target (e.g. maven or ant).  Some IDE refactor code can miss that link.</li>
  <li><p>FXMLLoader() does give you one clue. If you catch the exception you can look at the "getMessage()" ...</p>
  
  <pre><code>catch( Exception ex ){
         System.out.println("Exception on FXMLLoader.load()");
         System.out.println( ex.getMessage() );   //-- Doesn't show in stack dump
  }
  </code></pre></li>
  <li><p>Check your typing on FXML resources.  Small typos are the devil to identify and detect.  This goes for any string that isn't checked by a compiler or lint, not just FXML.  </p>
  
  <pre><code>// These two line are not the same:
  Parent root;
  root = FXMLLoader.load(getClass().getResource("Samplle.fxml"));
  root = FXMLLoader.load(getClass().getResource("Sample.fxml"));
  </code></pre></li>
  <li><p>There exception.getMessage() is: "<strong>Location required</strong>", for that typo in #6.</p></li>
  <li>If you edit the FXML manually, ensure that you <strong></strong> all relevant components.</li>
  <li><p>Remember to include the FXML namespace with "-d" files, e.g. needed on the outermost XML element.</p>
  
  <pre><code>&lt;TreeView id="treeView" fx:id="tree" xmlns:fx="http://javafx.com/fxml" ... &gt;
  </code></pre></li>
  </ol>
  
  <p>Hope something helps.  These are guesses based on small tests and trials.  Please fix embedded assumptions of misunderstandings about how things <em>actually</em> work.</p>
  
  <p><strong><em>see also</em></strong>:</p>
  
  <ol>
  <li><a href="https://stackoverflow.com/questions/20661209/javafx-loading-fxml-file-error">JavaFX - loading FXML file error</a></li>
  <li><a href="https://stackoverflow.com/questions/12132958/android-diagnostic-tool-for-applications">Android diagnostic tool for applications</a> (use case)</li>
  <li><a href="https://stackoverflow.com/questions/19097943/i-would-like-to-override-fxmlloader-how-can-i-do-that">I would like to override FXMLLoader. How can I do that?</a></li>
  <li><a href="https://stackoverflow.com/questions/19265954/how-does-fxmlloader-load-the-fxmls-controller">How does FXMLLoader load the FXML&#39;s controller?</a></li>
  <li><a href="https://stackoverflow.com/questions/18531283/cannot-locate-the-fxml-error-for-javafx">Cannot locate the fxml error for JavaFX</a> (use case)</li>
  <li><a href="http://docs.oracle.com/javafx/2/api/javafx/fxml/FXMLLoader.html" rel="nofollow noreferrer">Class javafx.fxml.FXMLLoader</a></li>
  <li><a href="http://docs.oracle.com/javafx/2/architecture/jfxpub-architecture.htm" rel="nofollow noreferrer">JavaFX Architecture</a> (PDF available), unfortunately there's nothing in here about FXML.</li>
  <li><a href="http://docs.oracle.com/javafx/2/api/javafx/fxml/doc-files/introduction_to_fxml.html" rel="nofollow noreferrer">Introduction to FXML</a></li>
  <li><a href="https://bitbucket.org/openjfxmirrors/openjfx-8-master-rt/src/tip/modules/fxml/src/main/java/javafx/fxml/FXMLLoader.java?at=default" rel="nofollow noreferrer">FXMLLoader.java source code</a></li>
  </ol>