Importing custom ADMX templates into Intune: upload errors, dependencies and fixes

Importing a vendor's ADMX template is the quickest way to manage an app the settings catalog doesn't cover, but Intune's import is strict: one missing dependency or unsupported element and the template never becomes usable. In this post I'll go through the failures you're likely to meet, what causes each one, how to fix it, and how to prove the settings reached a Windows device.

Symptoms#

• On the Import ADMX tab, the template shows a failed status instead of Available.
• The upload is rejected with a namespace error such as ADMX file referenced not found NamespaceMissing:Microsoft.Policies.Windows. Please upload it first.
• A newer version of an already imported template fails with a namespace error.
• The upload fails with a generic message; admins have reported errors such as Object reference not set to an instance of an object.
• The import works, but devices report errors for some settings or the app never sees the policy.

Why it happens#

Intune parses the ADMX and ADML on upload and turns each policy into a setting. On the device, Windows ingests the template through the Policy CSP and writes the registry values it defines. Most failures come down to one of these:

How to fix it#

1. Check dependencies before you upload#

Open the ADMX in a text editor and find the policyNamespaces node. target is the file's own namespace; every using element is a template that must already be imported. In Microsoft's example, kerberos.admx depends on Windows.admx:

<policyNamespaces>
  <target prefix="kerberos" namespace="Microsoft.Policies.Kerberos" />
  <using prefix="windows" namespace="Microsoft.Policies.Windows" />
</policyNamespaces>

For a whole folder of templates, let PowerShell list them:

Get-ChildItem -Path 'C:\ADMXTemplates' -Filter *.admx | ForEach-Object {
    [xml]$admx = Get-Content -Path $_.FullName -Raw
    $ns = $admx.policyDefinitions.policyNamespaces
    [pscustomobject]@{
        File      = $_.Name
        Namespace = $ns.target.namespace
        DependsOn = ($ns.'using'.namespace) -join ', '
    }
}

2. Import in dependency order#

1. Delete the failed entry from the Import ADMX tab.
2. Go to Devices › Manage devices › Configuration › Import ADMX › Import. Upload the prerequisite first (for Firefox, mozilla.admx) with its ADML from the en-US folder, confirm the language, then select Next and Create.
3. Select Refresh until it shows Available.
4. Import the dependent pair (firefox.admx and firefox.adml).

If the missing namespace is Microsoft.Policies.Windows, first import Windows.admx from C:\Windows\PolicyDefinitions and Windows.adml from its en-US subfolder. Use it only as a parent namespace; configure Windows' own settings in the settings catalog.

3. Work within the limits#

• Language: one en-US ADML per ADMX, taken from the same vendor download so strings and presentation IDs match.
• Size: each file must be 1 MB or smaller.
• Count: 20 ADMX files in total, prerequisites included. To free a slot, delete the profiles that use a template, then delete dependent files before their prerequisites.
• Combo boxes: find them before you upload.

Get-ChildItem -Path 'C:\ADMXTemplates' -Recurse -Include *.adml |
    Select-String -Pattern '<comboBox' -List |
    Select-Object Path

A combo box is an ADML presentation control bound to a text element in the ADMX. For a vendor template, find the setting in the settings catalog or deliver it another way (step 5); in a template you maintain, swap it for a plain text box.

4. Replace a template that's already imported#

1. Replace it: record the configured values, delete every profile using the template, delete the old ADMX, import the new pair and re-create the profiles in one change window.
2. Version it: for a template you own, give the new version a different namespace (add a version number), put the new settings in it and import it alongside the original.

5. Check where the settings write#

Windows doesn't let ingested templates write under the System, Software\Microsoft or Software\Policies\Microsoft keys, apart from a short allow-list of exceptions, most of them Office-related. Check the key attribute of each policy in the ADMX; vendor templates normally write under Software\Policies\<Vendor>, which is fine. If yours targets a protected area, use the settings catalog, a Remediations script or a Win32 app instead.

Verify the fix#

1. Every file in the chain shows Available on the Import ADMX tab.
2. Create the profile in Devices › Manage devices › Configuration › Create › New policy: Windows 10 and later, Templates › Imported Administrative templates (Preview). Configure a setting or two and assign it to a pilot group. Whether you target users or devices, computer settings go to HKLM and user settings to HKCU.
3. Sync a pilot device and confirm the profile reports Succeeded.
4. On the device, check Applications and Services Logs › Microsoft › Windows › DeviceManagement-Enterprise-Diagnostics-Provider › Admin in Event Viewer for errors from the sync.
5. Read the value from the key named in the ADMX and check the app itself; Firefox lists active policies on about:policies.

# Key and value names come from the <policy> element in the ADMX
Get-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\Mozilla\Firefox' -ErrorAction SilentlyContinue

Still failing? The MDM diagnostic report shows what the device received; see Finding and fixing Intune policy conflicts with the MDM diagnostic report.

Prevent it next time#

• Import only what the settings catalog doesn't already offer.
• Keep a folder per app with the ADMX, its matching en-US ADML and a note of its dependencies.
• Import prerequisites first and wait for Available before the next file.
• Treat the 20-file limit as a budget and remove templates you no longer use.
• For your own templates, use a unique, versioned namespace, avoid combo boxes and write under Software\Policies\<YourCompany>.

References#

• Import custom ADMX and ADML administrative templates into Microsoft Intune
• Understanding ADMX policies