Local -OutputPath is broken on Linux: hardcoded backslash makes checkpoint paths unopenable

[sambetts]

Local -OutputPath is broken on Linux: hardcoded '\' separator makes checkpoint paths unopenable

Repo: microsoft/PAX
Version: v1.11.15

Summary

When -OutputPath is a local path, PAX normalises it to directory form by appending a hardcoded backslash:

PAX_Purview_Audit_Log_Processor_v1.11.15.ps1, lines 7240 and 7255:

if (-not $OutputPath.EndsWith('\') -and -not $OutputPath.EndsWith('/')) {
    $OutputPath = $OutputPath + '\'
}

On Linux, \ is a legal filename character, not a separator. Passing -OutputPath /tmp/pax-output therefore yields /tmp/pax-output\, and every derived path is built underneath a directory that doesn't exist:

G-9: Failed to acquire checkpoint lock at /tmp/pax-output\/.pax_checkpoint_20260826_103115.json.lock:
Exception calling "Open" with "4" argument(s): "Could not find a part of the path
'/tmp/pax-output\/.pax_checkpoint_20260826_103115.json.lock'." Another process may have raced in.

The run aborts before any data is fetched.

Why the error is misleading

It is reported as a checkpoint lock contention problem — "Another process may have raced in" — which sends you looking for a stale lock or a concurrent run. The actual fault is the path separator, and the backslash is easy to miss inside a long path string.

Why it isn't caught by the shipped container guidance

fabric_resources/ documents running PAX in an Azure Container Apps Job, i.e. on Linux — but always with -OutputPath pointing at a SharePoint or OneLake URL. That takes the remote-output branch, which builds the scratch directory correctly:

line 7447-7448:

$sep = [System.IO.Path]::DirectorySeparatorChar
if (-not $OutputPath.EndsWith($sep)) { $OutputPath = $OutputPath + $sep }

So the bug only bites when a Linux host stages output locally — e.g. exporting to a local directory and then uploading, or writing to a mounted volume. Both are reasonable containerised patterns.

Reproduction

Linux container (mcr.microsoft.com/powershell:lts-7.4-ubuntu-22.04, the base used by fabric_resources/Dockerfile/PAX.Dockerfile):

pwsh -File PAX_Purview_Audit_Log_Processor_v1.11.15.ps1 \
  -Rollup -IncludeUserInfo -Auth AppRegistration \
  -TenantId <t> -ClientId <c> -ClientSecret <s> \
  -StartDate 2026-08-23 -EndDate 2026-08-27 \
  -OutputPath /tmp/pax-output \
  -OutputPathUserInfo /tmp/pax-output \
  -OutputPathLog /tmp/pax-output

Fails immediately with the G-9 error above.

Workaround

Pass a trailing separator on every -OutputPath*, since the append is skipped when one is already present:

-OutputPath /tmp/pax-output/

With that single change the same command runs to completion (62 partitions, rollup CSVs written).

Suggested fix

Use [System.IO.Path]::DirectorySeparatorChar at lines 7240 and 7255, matching what line 7448 already does. Optionally also accept / as a separator on Windows, which .NET handles natively.

[Rance9]

Hi Sam Betts (@sambetts),

Thanks for this, and apologies for the slow reply.

Confirmed on every point. L7240 and L7255 append a hardcoded , while the remote-output branch at L7447-7448 does it correctly with DirectorySeparatorChar. Your reproduction holds, and so does the workaround: the append is skipped when a separator is already present, so a trailing / on each -OutputPath* is a valid stopgap for anyone who hits this before the fix ships.

Your diagnosis was sharper than the report gives itself credit for. We swept the script for hardcoded backslash path handling, and those two are the only sites of their kind in the file. Everything else already uses DirectorySeparatorChar. The guard immediately above each one also already tests for both \ and /, so only the append is wrong, which is precisely where you pointed. That also means your optional suggestion about accepting / on Windows is already in place, so no change is needed there.

We are taking your suggested fix. Both appends move to [System.IO.Path]::DirectorySeparatorChar, and the guards stay as they are.

Your point about the misleading error is a separate defect and we are addressing it as well. The lock acquisition is wrapped in a catch-all that reports every failure as a race, so a missing directory, a permissions problem, and genuine contention all surface as "Another process may have raced in." There is already a correctly worded message elsewhere in that function for real contention, so the fix is to classify the exception rather than assume one. You are right that as written it sends you hunting for a stale lock.

Your read on why the container guidance missed it is also correct, and useful to us. The documented Azure Container Apps Job examples all point -OutputPath at a SharePoint or OneLake URL, which takes the remote branch, so local staging on Linux was the one shape that never got exercised. Staging locally and then uploading, or writing to a mounted volume, are both reasonable patterns and should work.

Both fixes are going into the next release, which should be within the next couple of weeks. There are a lot of feature enhancements in the next version, and will be released as v2.0.0.

Thanks again for the level of detail here. A reproduction, the container base image, the contrast against the remote-output branch, and a correct fix is about as actionable as a bug report gets, and it made this straightforward to confirm.

Best regards,
-The Microsoft Copilot Growth ROI Analytics Team-