[[ml-troubleshooting]]
== {xpackml} Troubleshooting

Use the information in this section to troubleshoot common problems and find
answers for frequently asked questions.

* <<ml-rollingupgrade>>
* <<ml-mappingclash>>

To get help, see <<xpack-help>>.

[[ml-rollingupgrade]]
=== Machine learning features unavailable after rolling upgrade

This problem occurs after you upgrade all of the nodes in your cluster to
{version} by using rolling upgrades. When you try to use {xpackml} features for
the first time, all attempts fail, though `GET _xpack` and `GET _xpack/usage`
indicate that {xpack} is enabled.

*Symptoms:*

* Errors when you click *Machine Learning* in {kib}.
For example: `Jobs list could not be created` and `An internal server error occurred`.
* Null pointer and remote transport exceptions when you run {ml} APIs such as
`GET _xpack/ml/anomaly_detectors` and `GET _xpack/ml/datafeeds`.
* Errors in the log files on the master nodes.
For example: `unable to install ml metadata upon startup`

*Resolution:*

After you upgrade all master-eligible nodes to {es} {version} and {xpack}
{version}, restart the current master node, which triggers the {xpackml}
features to re-initialize.

For more information, see {ref}/rolling-upgrades.html[Rolling upgrades].

[[ml-mappingclash]]
=== Job creation failure due to mapping clash

This problem occurs when you try to create a job.

*Symptoms:*

* Illegal argument exception occurs when you click *Create Job* in {kib} or run
the create job API. For example:
`Save failed: [status_exception] This job would cause a mapping clash
with existing field [field_name] - avoid the clash by assigning a dedicated
results index` or `Save failed: [illegal_argument_exception] Can't merge a non
object mapping [field_name] with an object mapping [field_name]`.

*Resolution:*

This issue typically occurs when two or more jobs store their results in the
same index and the results contain fields with the same name but different
data types or different `fields` settings. 

By default, {ml} results are stored in the `.ml-anomalies-shared` index in {es}.
To resolve this issue, click *Advanced > Use dedicated index* when you create
the job in {kib}. If you are using the create job API, specify an index name in
the `results_index_name` property.