Second, similar to a problem I had before, you have to be careful with namespaces. I had something like:
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
for $i in /some/path/in/input/document
And the some path in input document wasn't returning any data, even though I knew there was data at that path. The issue here is documented in the spec. The default namespace of xhtml in the direct constructor becomes the default namespace for the path step elements. I found the simplest way to fix this was to move the path logic into a declared function that was outside of the direct constructor where the XHTML default namespace wasn't in scope. I could have also re-declared the default namespace or prefixed all xhtml nodes, but that wouldn't look as clean.
Speaking of declared functions, I also was tripped up for a little bit by the fact that declared functions don't get the same context passed to them automatically as the does the main execution of the same module. This exhibited by the runtime telling that the path I was executing was invalid as the context was unknown. Again the spec tells me that the context is undefined. In order to deal with this, you just need to pass the context of interest to the function and have all relative paths work off of the passed context.
Finally, I did get tripped up on XSLT 2.0 as well. When running a stylesheet that took no direct input, I mistakenly called setXSLTInitialMode (good for defining multiple paths through a XSLT 2.0 stylesheet) instead of setXSLTInitialTemplate (good for loading data from multiple input docs or unparsed text, etc.). Luckily, the errors of IXJXE0793E and ERR XTDE0045 came out in the logs and helped me spot the code completion generated typo.
Hopefully some small help if, like myself, you're working to use XQuery/XSLT 2.0 more and more in your ever day coding. Now, if I could just stop typing ";" at the end of XQuery let statements.