Debugging guide

When running an ml-gradle task such as "mlDeploy", a number of things can go wrong - bad connection information, invalid username/password, bad resource files, bad REST modules, etc. This page intends to guide you through how to debug any errors that you run into before you have to ask for help.

Do this first

Before going any further, run the task that just failed with Gradle's info-level logging enabled - let's assume it was mlDeploy that failed:

gradle -i mlDeploy

With info-level logging enabled, ml-gradle will log a number of useful things:

• Any overridden properties will be logged (except for passwords)
• Every command executed by mlDeploy will be logged

mlDeploy, along with resource-specific tasks such as mlDeployUsers or mlDeployDatabases, run a series of commands, with generally one command per resource type. The logging for each command shows what directory the command looks along with each file that it processes. In the case of a malformed resource file, info-level logging should allow you to easily identify which file was unable to be processed.

And you'll often want to do this too

Whenever Gradle throws an error, it prints the following helpful information too:

Run with --stacktrace option to get the stack trace. Run with --debug option to get more log output. Run with --scan to get full insights.

If the error message from info-level logging doesn't tell you exactly what the problem is, then follow Gradle's advice and include the "--stacktrace" option as well:

gradle -i --stacktrace mlDeploy

You can include "--debug" or ("-d") too, but it's not common that this will expose an ml-gradle problem that info-level logging and the stacktrace don't already show. And debug logging is very verbose, because you get all Gradle debug logging, not just ml-gradle's debug logging.

Debugging resource files

In the event of a bad resource file (resource = database, or user, or role, etc) - e.g. the file has malformed JSON or XML, or the contents of the resource file don't conform to the Manage API schema for that resource - the info-level logging above should identify the file that ml-gradle can't load.

In the case of malformed JSON/XML, ml-gradle should log an error that explains the issue if you include the "--stacktrace" option mentioned above. So if you have e.g. a malformed XML file for a role, you'll see logging like this:

gradle -i --stacktrace mlDeployRoles
... omitting some gradle logging ...
Execution failed for task ':mlDeployRoles'.
> Unable to read resource payload: null
... omitting more logging and a lot of the stack trace ...
Caused by: org.xml.sax.SAXParseException; lineNumber: 2; columnNumber: 1; XML document structures must start and end within the same entity.

In the case of a resource file that the Manage API can't process, the error thrown by the Manage API generally should explain the issue, and you'll get that issue without the "--stacktrace" flag too:

gradle -i mlDeployRoles
... omitting some gradle logging ...
Execution failed for task ':mlDeployRoles'.
> Unable to read resource payload: unexpected element (uri:"", local:"bad-role"). Expected elements are <{http://marklogic.com/manage}role-properties>

Debugging module loading

Deploying an application to MarkLogic generally involves two steps - deploying resources (databases, servers, users, etc), and loading modules into a modules database. Deploying resources happens via the Manage API on port 8002, while loading modules happens via a combination of two ports - 8000 for non-REST modules (called "asset" modules in the REST API docs), and an application-specific port for REST modules (options, services, and transforms).

If your deployment fails, you'll want to know if it's because of an error with deploying a resource or loading a module. Info-level logging will tell you this fairly quickly. If we have e.g. a bad REST module, like an invalid options file, we'll get logging like this:

gradle -i mlDeploy
... omitting some gradle logging ...
Execution failed for task ':mlDeployApp'.
> Error occurred while loading REST modules: Local message: /config/query write failed: Bad Request. Server Message: RESTAPI-INVALIDCONTENT: (err:FOER0000) Invalid content: Unexpected Payload...

For more information, please see Debugging module loading.