Backup-DbaDatabase - Improve error messages for mapped drive path failures

When SQL Server cannot access a drive-letter path (mapped drive), explain
that net use mappings are per user session and not visible to the SQL Server
service account, and suggest using a UNC path instead. Also detect OS Error 3
in backup failures and surface the same guidance in the catch block.

Fixes #10366

(do Backup-DbaDatabase)

Co-authored-by: Andreas Jordan <andreasjordan@users.noreply.github.com>

Author: github-actions[bot]

public/Backup-DbaDatabase.ps1

@@ -163,6 +163,7 @@ function Backup-DbaDatabase {
         Skips path validation checks before backup operations, useful when SQL Server has limited filesystem access.
         Bypasses safety checks that normally prevent backup failures due to permissions or missing paths.
         Use with caution as it may result in backup failures that could have been prevented.
+        Note: This does not help when using mapped drives (e.g. net use). Mapped drives are only visible to the user session that created them, not to the SQL Server service account. Use UNC paths (e.g. \\server\share\path) for network locations.
 
     .PARAMETER OutputScriptOnly
         Generates and returns the T-SQL BACKUP commands without executing them.
@@ -918,7 +919,11 @@ function Backup-DbaDatabase {
                         if (($BuildPath -eq $true) -or ($CreateFolder -eq $True)) {
                             $null = New-DbaDirectory -SqlInstance $server -Path $parentPath
                         } else {
-                            $failreason += "SQL Server cannot check if $parentPath exists. You can try disabling this check with -IgnoreFileChecks"
+                            if ($parentPath -match "^[A-Za-z]:\\") {
+                                $failreason += "SQL Server cannot access $parentPath. Drive letter paths (e.g. $($parentPath.Substring(0,2))) are mapped per user session and are not visible to the SQL Server service account. Use a UNC path instead (e.g. \\server\share\path)."
+                            } else {
+                                $failreason += "SQL Server cannot access $parentPath. Verify that the SQL Server service account has read/write permissions to this path. You can bypass this check with -IgnoreFileChecks, but the backup will still fail if SQL Server cannot access the path."
+                            }
                             $failures += $failreason
                             Write-Message -Level Warning -Message "$failreason"
                         }
@@ -1072,12 +1077,16 @@ function Backup-DbaDatabase {
                         }
                     }
                 } catch {
-                    if ($NoRecovery -and ($_.Exception.InnerException.InnerException.InnerException -like '*cannot be opened. It is in the middle of a restore.')) {
+                    if ($NoRecovery -and ($_.Exception.InnerException.InnerException.InnerException -like "*cannot be opened. It is in the middle of a restore.")) {
                         Write-Message -Message "Exception thrown by db going into restoring mode due to recovery" -Level Verbose
                     } else {
                         Write-Progress -Id $ProgressId -Activity "Backup" -Completed
                         Write-Progress -Id $topProgressId -Activity "Backup" -Completed
-                        Stop-Function -message "Backup of [$dbName] failed" -ErrorRecord $_ -Target $dbName -Continue
+                        $errMsg = "Backup of [$dbName] failed"
+                        if ($_.Exception.Message -like "*Operating system error 3*" -or $_.Exception.InnerException.Message -like "*Operating system error 3*") {
+                            $errMsg += " | The SQL Server service account cannot find the backup path. If you used a mapped drive (e.g. net use), use a UNC path instead (e.g. \\server\share\path), as mapped drives are not visible to the SQL Server service account. Run Test-DbaPath -SqlInstance $($server.Name) -Path `"$humanBackupFile`" to verify accessibility from SQL Server."
+                        }
+                        Stop-Function -message $errMsg -ErrorRecord $_ -Target $dbName -Continue
                         $BackupComplete = $false
                     }
                 }