MarkLogic 9 Product DocumentationJava Application Developer's Guide — Chapter 17
Troubleshooting
This chapter describes how to troubleshoot errors while programming in the Java API, and contains the following sections:
Error Detection
As you would expect, the Java API client indicates errors by throwing exceptions. It does not return errors or otherwise indicate problems by any other means. The exceptions are located in com.marklogic.client and are:
FailedRequestException: Indicates a problem at the REST API level.ForbiddenUserException: Indicates credentials used to connect to a REST instance are not sufficient for the requested task. Equivalent to a403HTTP status code.MarkLogicBindingException: Indicates a problem binding a value.MarkLogicInternalException: Indicates a defect in the API. Call MarkLogic Support.MarkLogicIOException:RuntimeExceptionThrown when a code block internally throwsjava.lang.IOException.MarkLogicServerException: The MarkLogic REST Server threw an exception.ResourceNotFoundException: Thrown when the server responds with an HTTP404status.UnauthorizedUserException: Thrown when a user attempts an operation to which they do not have the rights for.
General Troubleshooting Techniques
The following are some general guidelines for troubleshooting your program.
- To troubleshoot unexpected search results, pass the query option for
debug, which returns errors in the query options, and thereturn-qtextoption, which returns the pre-parsed query text for the search. - Remember that documents with no read permission are hidden.
- To troubleshoot exceptions, pay close attention to any messages returned from the server.
- Set the MarkLogic Server error log to
debugand view the server log (<marklogic-dir>/Logs/ErrorLog.txt) for more details. - To monitor the HTTP requests against the REST Server, look at the access logs under the
<marklogic-dir>/Logsdirectory for your REST App Server (for example,1234_AccessLog.txtfor the server running on port 1234). - Configure managers with a request logger to confirm requests are correct.
- To troubleshoot extensions, first execute the XQuery code in an XQuery environment. Then look at the requests and server log.
- Check the query options builder output to make sure it is what you expect, either with
QueryOptionsHandle.toString(), which outputs the XML representation of the query options, or by checking the stored options against what is expected. Errors reported by MarkLogic Server refer to the structure of this document. - When you have a mismatch between query options and existing indexes, you can look at the
/v1/config/indexes?format=htmlendpoint on your REST Server. - If you want a closer look at the requests against the REST Server, use a network sniffer to watch the HTTP trafic against the REST Server. You can also try to execute an equivalent request for the REST API using cURL or some other HTTP client.