PowerShell Out-File default encoding (UTF-16) breaks tools in CI

Windows PowerShell 5.1 writes UTF-16LE with a BOM by default from Out-File and > redirection. Tools expecting UTF-8 then choke on the BOM or the null bytes, failing in confusing ways.

What this error means

A file written in one step is rejected by a parser in the next step: a YAML/JSON loader reports an unexpected character at the start, or a tool reads garbled text. Deterministic for the default encoding.

# config.json written via >  then parsed:
SyntaxError: Unexpected token  in JSON at position 0
# the leading bytes are FF FE (UTF-16 BOM), not '{'

Common causes

Windows PowerShell 5.1 defaults to UTF-16

Out-File and > in 5.1 default to Unicode (UTF-16LE) with a BOM. Tools written for UTF-8 cannot parse it.

Even UTF-8 output may include a BOM

Some encoders emit a UTF-8 BOM that strict parsers reject at position 0.

How to fix it

Specify UTF-8 explicitly

Force UTF-8 on every write so downstream tools get the bytes they expect.

$json | Out-File -FilePath config.json -Encoding utf8
# PowerShell 7: utf8NoBOM avoids the BOM entirely
$json | Out-File -FilePath config.json -Encoding utf8NoBOM

Write bytes without a BOM

Use the .NET API for guaranteed BOM-free UTF-8.

$enc = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText('config.json', $json, $enc)

How to prevent it

• Always pass -Encoding utf8 (or utf8NoBOM on PS7) when writing files that other tools read, or set $PSDefaultParameterValues to default Out-File to UTF-8.

Related guides