Microsoft Sentinel
Troubleshooting

Troubleshoot Microsoft Sentinel analytics rule migration blockers | Microsoft Learn

In brief

Microsoft added guidance for using migration reports, matching blocker codes, safely editing and validating Microsoft Sentinel analytics rules, and reassessing migration eligibility.

What Defender admins need to know

Administrators can use the checklist and blocker index to investigate migration issues while preserving existing detection behavior and dependent automation.

Summaries are generated from the documentation change itself.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

new file mode 100644

layout: Conceptual title: Troubleshoot Microsoft Sentinel analytics rule migration blockers | Microsoft Learn canonicalUrl: https://learn.microsoft.com/en-us/azure/sentinel/transition-custom-detections-migration-blockers breadcrumb_path: breadcrumb/toc.json feedback_help_link_url: https://learn.microsoft.com/answers/tags/423/microsoft-sentinel/ feedback_help_link_type: get-help-at-qna feedback_product_url: https://feedback.azure.com/d365community/forum/79b1327d-d925-ec11-b6e6-000d3a4f06a4 feedback_system: Standard learn_banner_products:


Troubleshoot Microsoft Sentinel analytics rule migration blockers | Microsoft Learn

When an analytics rule shows Migration isn't available, use its migration report to identify the blocker. Match the report code to the guidance, decide whether a change is safe, and validate the rule before reassessing eligibility.

Before editing a rule, review the access, backup, and validation prerequisites.

Prerequisites

  • Permissions to edit analytics rules and manage custom detections.
  • An exported or copied rule configuration that you can restore.
  • A representative validation period and expected test events.
  • A list of automation rules, playbooks, workbooks, and integrations that depend on the current alerts.

Important

Rule changes can affect alert volume, timing, entities, incidents, and automation. Don't change a rule only to get migration eligibility. Keep the original analytics rule enabled until migration is explicitly completed. Validate every change, and retain the original behavior when the operational risk is greater than the benefit of migrating now.

Troubleshooting checklist

Identify the reported blocker and the safest next action before editing.

Download and match the report

Use the latest report to identify the blocker and assess a safe resolution.

  1. In the SOC optimization recommendation, select Download report for rules marked Migration isn't available.
  2. Match the error code or message to the blocker index.
  3. Record the current rule configuration and expected behavior.
  4. Decide whether to edit the rule, evaluate a separate redesign, or retain it until a supported migration path is available.

Validate source-rule changes

Test the edited analytics rule before requesting reassessment.

  1. Change one blocker at a time when practical.
  2. Save the edited analytics rule and validate that it still detects the intended activity.
  3. Compare alert volume, timing, entities, incident behavior, and dependent automation.
  4. Reassess eligibility only after the changes preserve detection intent.

Causes and solutions

Use the exact report code to find the relevant category. Match the report wording below to the message in your downloaded report. Values in braces are placeholders. A rule can have more than one blocker.

BlockerReport code
Dynamic alert propertiesUnsupportedAlertDetailsOverride, UnsupportedAlertProperty, InvalidDynamicProperties
Unsupported entity typeUnsupportedEntityType
Unsupported Sentinel entities mappingUnsupportedSentinelEntitiesMapping
Alerts without incidentsUnsupportedIncidentConfiguration
Secondary workspaceNonPrimaryLogAnalyticsWorkspace
Cross-workspace queryCrossWorkspaceCustomDetectionNotSupported
NRT watchlistNrtFunctionsNotSupported
NRT multiple tablesNrtMultipleTablesNotSupported
NRT workspace operatorNrtCrossWorkspaceNotSupported
Other streaming failureNrtStreamingIncompatible, NrtStreamingCompatibilityUnknown
NRT externaldataNrtExternalDataNotSupported
NRT event groupingUnsupportedNrtSingleAlertGrouping
ASIM, custom, or nested functionsUnsupportedLogAnalyticsCustomFunction, NrtFunctionsNotSupported, HuntingRuleWithPrivateFunction, HuntingRuleQuerySyntaxErrors
SuppressionUnsupportedSuppression
Non-default thresholdUnsupportedThreshold

Dynamic alert properties and alert-details overrides

Report codes:UnsupportedAlertDetailsOverride, UnsupportedAlertProperty, InvalidDynamicProperties.

Report wording: The Analytics Rule overrides dynamic alert details; Custom Detections have no equivalent override.

Resolution: Remove the dynamic alert-details overrides, retaining values analysts need as custom details. If several static values are required, splitting the rule is a redesign to validate before adoption. Apply changes only when they preserve detection intent.

Unsupported entity type

Report code:UnsupportedEntityType.

Report wording: The rule contains an entity type that is not supported by custom detections. Unsupported AnalyticsEntityType: {value}

Resolution: Replace the unsupported mapping with a supported entity type that carries the same information. Remove the mapping only if investigation and automation don't need it.

Unsupported Sentinel entities mapping

Report code:UnsupportedSentinelEntitiesMapping.

Report wording: The rule uses Sentinel prebuilt entity mappings that are not supported by custom detection alert creation.

Resolution: Replace the prebuilt mapping with explicit, supported entity mappings taken from the query results.

Alerts without incidents

Report code:UnsupportedIncidentConfiguration.

Report wording: The Analytics Rule has custom incident configuration; Custom Detections have no incident configuration equivalent.

Resolution: If the behavior change is acceptable, enable incident creation with the default settings. Use Defender alert tuning or automation rules if incidents should be auto-resolved or hidden. Validate the changed incident behavior and dependent automation before migration.

Rule runs on a secondary workspace

Report code:NonPrimaryLogAnalyticsWorkspace.

Report wording: Custom Detections that query Log Analytics tables can only be created on the tenant's primary workspace.

Resolution: Recreate the rule against equivalent data in the primary workspace. Keep the original enabled until the replacement is validated. If equivalent data isn't available locally, retain the rule in Sentinel.

Cross-workspace query using workspace()

Report code:CrossWorkspaceCustomDetectionNotSupported.

Report wording: This Analytics Rule references multiple workspaces ({WorkspaceIds}). Custom Detections require a single workspace. Rewrite the query to use one workspace and try again.

Resolution: Replace every workspace() call with equivalent local tables, or split the rule and retain the remote-data logic in Sentinel.

NRT rule uses a watchlist

Report code:NrtFunctionsNotSupported.

Report wording: This NRT Analytics Rule references query functions ({FunctionNames}). Streaming Custom Detections do not support function references. Rewrite the query using supported KQL without functions and try again.

Resolution: Remove the watchlist lookup only if detection intent is preserved. If the lookup is essential, change the rule to a scheduled analytics rule before migration.

NRT rule queries multiple tables

Report code:NrtMultipleTablesNotSupported.

Report wording: This NRT Analytics Rule references multiple tables ({DistinctTableNames}); streaming Custom Detections require a single table. Rewrite the query to use one table and try again.

Resolution: Rewrite the query to use one table, or split it into single-table detections. If the cross-table logic is essential, use a scheduled analytics rule.

NRT rule uses the workspace operator

Report code:NrtCrossWorkspaceNotSupported.

Report wording: This NRT Analytics Rule references multiple workspaces ({WorkspaceIds}). Streaming Custom Detections require a single workspace. Rewrite the query to use one workspace and try again.

Resolution: Replace each workspace() call with the equivalent local table, or retain the remote-data logic in a separate Sentinel rule.

Other streaming failure

Report codes:NrtStreamingIncompatible, NrtStreamingCompatibilityUnknown.

Report wording for NrtStreamingIncompatible: The NRT Analytics Rule could not be validated as compatible with streaming Custom Detections. {StreamingCompatibilityReason}

Report wording for NrtStreamingCompatibilityUnknown: Streaming compatibility could not be determined for this NRT Analytics Rule; migration requires a confirmed compatible query.

Resolution: Simplify the query to single-table streaming KQL without functions, joins, unions, or external references. If the required logic can't be preserved, use a scheduled analytics rule.

NRT query uses externaldata

Report code:NrtExternalDataNotSupported.

Report wording: This NRT Analytics Rule uses the externaldata operator, which is not supported in streaming Custom Detections. Remove the externaldata reference and try again.

Resolution: Write the external data values directly into the query filter, or use a scheduled analytics rule if the external data is essential.

NRT rule uses event grouping

Report code:UnsupportedNrtSingleAlertGrouping.

Report wording: NRT Custom Detections don't support grouping all query results into a single alert.

Resolution: Switch the rule to one alert per event only when that behavior is acceptable. If events need to be grouped into a single alert, use a scheduled analytics rule.

ASIM, custom, or nested functions

Report codes:UnsupportedLogAnalyticsCustomFunction, NrtFunctionsNotSupported, HuntingRuleWithPrivateFunction, HuntingRuleQuerySyntaxErrors.

Report wording: This Analytics Rule uses the Log Analytics custom function '{FunctionName}'. Custom functions aren't currently supported for migration to Custom Detections. Inline the function logic in the rule query and try again.

Resolution: Inline the logic of every custom, ASIM, or nested function so that the rule query no longer calls saved functions. Validate that the rewritten query preserves the intended behavior.

Suppression is enabled

Report code:UnsupportedSuppression.

Report wording: The Analytics Rule uses alert suppression; Custom Detections have no suppression equivalent.

Resolution: Turn off Stop running query after alert is generated only when the change is acceptable. Handle noise with KQL aggregation, alert tuning, or automation, and validate the resulting alert volume.

Non-default trigger threshold

Report code:UnsupportedThreshold.

Report wording: The Analytics Rule only alerts after {N} matches ({Operator}); Custom Detections have no threshold equivalent. A structural conversion can instead return: Unsupported AlertTriggerOperator: {value}.

Resolution: Move the threshold into the query by aggregating and filtering. Then set the alert threshold to greater than 0 and validate the results.

Reassess eligibility

Eligibility refresh isn't instant. After saving and validating changes:

  1. Return to the SOC optimization recommendation and open Analytic rules.
  2. Select Refresh and wait while the rule shows Under evaluation.
  3. If the rule becomes Ready to migrate, select it and follow the single-rule or bulk migration flow.
  4. If Migration isn't available remains, download a new report and resolve the next blocker.
  5. Repeat the edit, validation, and reassessment cycle until the rule is ready or you choose to retain it in Sentinel.

Review unresolved issues

Use the following checks if eligibility or detection behavior doesn't match expectations.

IssueNext action
The rule is still unavailable.Download a new report because another blocker might remain.
The rule stays Under evaluation.Wait, select Refresh, and confirm that the saved rule and workspace match the recommendation.
Alert volume increased after editing.Restore the original configuration or tune the query before migration.
Entity or incident quality degraded.Restore the stronger mapping or incident behavior and retain the rule until support is available.
The rewritten query produces different results.Compare parameters, functions, time filters, joins, projected columns, and result schema.
Required data isn't available locally.Retain the rule in Sentinel. A rule edit doesn't resolve the data-availability constraint.
\ No newline at end of file