Troubleshooting

This chapter describes how to troubleshoot errors while programming in the Java API, and contains the following sections:

• Error Detection
• General Troubleshooting Techniques

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 a 403 HTTP status code.

• MarkLogicBindingException: Indicates a problem binding a value.

• MarkLogicInternalException: Indicates a defect in the API. Call MarkLogic Support.

• MarkLogicIOException: RuntimeException Thrown when a code block internally throws java.lang.IOException.

• MarkLogicServerException: The MarkLogic REST Server threw an exception.

• ResourceNotFoundException: Thrown when the server responds with an HTTP 404 status.

• 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 the return-qtext option, 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 debug and 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>/Logs directory for your REST App Server (for example, 1234_AccessLog.txt for 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=html endpoint 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.