OneDrive Known Folder Move Failures: A Zero-Touch Fix

#The Old Way vs the New Way

The old way of handling a failed Known Folder Move (KFM) enrolment looks like this: a user reports that their Desktop icons vanished, or worse, that Documents synced but Desktop did not, so files are scattered across two locations. A technician remotes in, opens the OneDrive settings pane, checks the sync icon for red exclamation marks, digs through %localappdata%MicrosoftOneDrivelogs, manually restarts the sync client, and re-triggers the KFM wizard by hand. Fifteen to thirty minutes per user, and it happens every single time a machine is re-imaged, a user changes their password in a way that breaks the token silently, or a GPO conflict quietly disables one of the three redirected folders.

The new way treats KFM failure as a telemetry event, not a ticket. Windows writes structured KFM error codes to the registry and to the OneDrive sync engine logs the moment redirection fails. We poll for those codes with a scheduled script, classify the failure by error code, and remediate automatically: re-run the ODOPEN redirection URI, repair broken registry pointers, or force a clean re-enrolment, all before the user notices their Desktop looks wrong. Escalation only happens when the automated remediation itself fails twice, which is the actual signal that a human is needed.

#Why KFM Fails So Often

Known Folder Move redirects Desktop, Documents, and Pictures into a user’s OneDrive folder so they sync automatically. It is deployed via the ODOPEN protocol handler or the KFMSilentOptIn / KFMBlockOptOut Group Policy values, targeted with the tenant GUID. It fails constantly in the following patterns:

• The tenant ID in the policy is stale after a tenant migration or B2B reconfiguration.
• The user’s OneDrive client has not fully authenticated before the KFM policy tries to fire, a race condition common on first login after imaging.
• One of the three folders (usually Desktop) is redirected by a legacy folder redirection GPO that conflicts with KFM, producing error code 0x8004def7 or similar library conflict errors.
• Local NTFS permissions on the existing Desktop folder are wrong (often from a previous profile) and OneDrive refuses to move files into a folder it does not fully own.

Each of these leaves a fingerprint in the registry under HKEY_CURRENT_USERSoftwareMicrosoftOneDriveAccounts<AccountGUID> and in the sync engine’s structured logs. That fingerprint is what we automate against.

#Prerequisites and Permissions

• OneDrive sync client version 22.230 or later (native KFM error reporting is more reliable from this build onward).
• Intune or GPO-managed KFM policy already deployed with a valid tenant GUID.
• Remote script execution capability: Intune remediation scripts, a Microsoft Endpoint Manager Proactive Remediation package, or an RMM tool that supports scheduled PowerShell with SYSTEM context.
• Minimum role: Intune Policy and Profile Manager (for deploying and updating remediation scripts) plus Cloud Device Administrator for querying Entra ID sign-in status if you extend this into conditional checks.
• Do not run the remediation script with domain admin credentials. SYSTEM context on the endpoint is sufficient and keeps blast radius local to the single device.
• Test scope: pilot on a device collection of 15 to 25 machines with known KFM history before tenant-wide rollout.

#Implementation Steps

1. Action: Deploy a detection script as an Intune Proactive Remediation, run in SYSTEM context on a 4-hour recurring schedule. Expected result: the script exits 1 for any device where KFM state is not fully redirected, triggering the paired remediation script. Evidence to capture: Intune remediation report showing detection failure count per device.
   Terminal

   1# Detect-KFMStatus.ps1
   2$ErrorActionPreference = 'Stop'
   3$accountsKey = 'HKCU:\Software\Microsoft\OneDrive\Accounts'
   4$failed = $false
   5
   6try {
   7    $accounts = Get-ChildItem -Path $accountsKey -ErrorAction Stop
   8    foreach ($acct in $accounts) {
   9        $kfmKey = Join-Path $acct.PSPath 'KFM'
   10        if (Test-Path $kfmKey) {
   11            $state = Get-ItemProperty -Path $kfmKey -ErrorAction SilentlyContinue
   12            foreach ($folder in @('Desktop','Documents','Pictures')) {
   13                $prop = "KfmFolderRedirectStatus_$folder"
   14                $val = $state.$prop
   15                if ($null -eq $val -or $val -ne 1) {
   16                    Write-Output "KFM not complete for $folder (value: $val)"
   17                    $failed = $true
   18                }
   19            }
   20        } else {
   21            Write-Output "No KFM key found under account $($acct.PSChildName)"
   22            $failed = $true
   23        }
   24    }
   25} catch {
   26    Write-Output "Detection error: $($_.Exception.Message)"
   27    $failed = $true
   28}
   29
   30if ($failed) { exit 1 } else { exit 0 }

   Expected output on a healthy device: no console text, exit code 0. On a broken device: lines such as KFM not complete for Desktop (value: 0) and exit code 1.

2. Action: Pair the detection script with a remediation script that re-triggers KFM via the ODOPEN protocol and repairs the common permission fault. Expected result: OneDrive silently re-runs the redirection wizard without user interaction. Evidence to capture: registry value flip from 0 to 1 under the KFM key, confirmed on next detection cycle.
   Terminal

   1# Remediate-KFM.ps1
   2$tenantId = '11111111-2222-3333-4444-555555555555'
   3$oneDriveExe = Join-Path $env:LOCALAPPDATA 'Microsoft\OneDrive\OneDrive.exe'
   4
   5# Step 1: fix ownership on existing shell folders so OneDrive can claim them
   6$shellFolders = @('Desktop','Documents','Pictures') | ForEach-Object {
   7    [Environment]::GetFolderPath($_)
   8}
   9foreach ($path in $shellFolders) {
   10    if (Test-Path $path) {
   11        $acl = Get-Acl $path
   12        $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
   13            $env:USERNAME, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow'
   14        )
   15        $acl.SetAccessRule($rule)
   16        Set-Acl -Path $path -AclObject $acl
   17    }
   18}
   19
   20# Step 2: kill and restart OneDrive to clear stuck sync engine state
   21Get-Process -Name OneDrive -ErrorAction SilentlyContinue | Stop-Process -Force
   22Start-Sleep -Seconds 3
   23
   24# Step 3: re-trigger KFM silent opt-in via ODOPEN protocol handler
   25$odopenUri = "odopen://sync?userEmail=$(whoami.exe /upn)&tenantId=$tenantId&av=KFM"
   26Start-Process -FilePath $oneDriveExe -ArgumentList '/background'
   27Start-Sleep -Seconds 5
   28Start-Process -FilePath $odopenUri
   29
   30Write-Output "KFM re-trigger dispatched for tenant $tenantId"

3. Action: Add a structured log parser that classifies the specific KFM error code before choosing a remediation path, rather than blindly re-running the same fix. Expected result: conflicting folder redirection GPOs (error 0x8004def7) are flagged separately from authentication races (error 0x8004de40), because the fix differs. Evidence to capture: a per-device error code tag written back to a custom Intune device category or a log-analytics table.
   Terminal

   1$logPath = Join-Path $env:LOCALAPPDATA 'Microsoft\OneDrive\logs\Business1'
   2$latestLog = Get-ChildItem -Path $logPath -Filter 'SyncDiagnostics.log' -ErrorAction SilentlyContinue |
   3    Sort-Object LastWriteTime -Descending | Select-Object -First 1
   4
   5if ($latestLog) {
   6    $content = Get-Content $latestLog.FullName -Tail 500
   7    $kfmErrors = $content | Select-String -Pattern 'KfmFolderRedirectError'
   8    foreach ($line in $kfmErrors) {
   9        if ($line -match '0x8004def7') {
   10            Write-Output "CONFLICT: Legacy folder redirection GPO detected. Manual GPO review required."
   11        } elseif ($line -match '0x8004de40') {
   12            Write-Output "AUTHRACE: Authentication not complete before KFM fired. Retry safe."
   13        } else {
   14            Write-Output "UNKNOWN: $line"
   15        }
   16    }
   17}

4. Action: Route the classified failures into a lightweight webhook so recurring conflict-type failures (which automation cannot safely fix) generate a single aggregated ticket per GPO conflict rather than one ticket per user. Expected result: a Teams or ITSM webhook receives one entry per unique conflict signature, deduplicated hourly. Evidence to capture: webhook delivery log showing payload received and ticket ID returned.
   JSON payload

   1{
   2  "deviceId": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
   3  "userUpn": "jane.doe@contoso.com",
   4  "kfmErrorCode": "0x8004def7",
   5  "classification": "CONFLICT",
   6  "folder": "Desktop",
   7  "detectedAtUtc": "2024-06-18T09:15:00Z",
   8  "remediationAttempted": true,
   9  "remediationResult": "failed-conflict-not-autoresolvable",
   10  "suggestedAction": "Remove legacy Folder Redirection GPO link for this OU"
   11}

5. Action: Schedule the detection and remediation pair to run twice daily and log a summary to a central location for trend review. Expected result: KFM failures are caught and fixed within a 12-hour window without any user-initiated contact. Evidence to capture: weekly Intune remediation report showing declining detection-failure counts across the fleet.

#Verification and Expected Evidence

Confirm success at three levels. First, on the endpoint, re-run the detection script manually and confirm exit code 0:

.Detect-KFMStatus.ps1; echo "Exit code: $LASTEXITCODE"

Expected output: Exit code: 0 with no failure lines printed. Second, check that the physical folder path has actually moved:

(New-Object -ComObject Shell.Application).NameSpace(0x10).Self.Path

Expected output: a path under C:Users<username>OneDrive - ContosoDesktop rather than the local profile path. Third, review the Intune remediation dashboard for the device cohort; expect the detection-failure rate to drop below 5 percent within two remediation cycles of initial rollout.

#Rollback

If the remediation script itself introduces problems, for example an ACL change that locks out a service account with special permissions on Desktop, roll back by disabling the remediation policy assignment in Intune (detection-only mode continues to run so you retain visibility) and restoring the prior ACL from a pre-change export. Always capture Get-Acl output to a file before the first production run of Step 2 so a restore command is a one-liner: Set-Acl -Path $path -AclObject (Import-Clixml -Path 'C:\Temp\PreKFM-ACL.xml'). Blast radius is a single user profile per execution; nothing here touches server-side OneDrive or SharePoint data.

#Failure and Escalation Conditions

Automated remediation should attempt the fix twice, twelve hours apart. Escalate to a human L2 technician when any of the following occurs: the same device fails detection three consecutive cycles after remediation; the classification engine returns CONFLICT (meaning a GPO must be edited by a person with Group Policy rights, which this script deliberately does not touch); or the OneDrive sync client itself is below the minimum supported build and needs a manual upgrade push. The monitoring signal that should wake a human outside business hours is a spike where more than 10 percent of a single OU’s devices fail detection within one polling cycle, since that pattern indicates a tenant-wide policy or authentication problem rather than isolated device drift.

#Measuring Ticket Deflection

Baseline your current KFM-related ticket volume for 30 days before rollout, tagging tickets with a category such as onedrive-kfm-manual. After deploying the detection and remediation pair, track three numbers monthly: total KFM-tagged tickets opened, average technician minutes per KFM ticket (should approach zero for auto-resolved cases), and the count of aggregated conflict-webhook entries that still require manual GPO work. A realistic target after 60 days is a 70 to 85 percent reduction in KFM-related tickets, with the remaining volume concentrated almost entirely in the CONFLICT classification, which tells you exactly where to spend remaining engineering effort: auditing and retiring legacy folder redirection GPOs.