TL;DR

Claude Code cloud sessions don’t install the plugins a repository’s .claude/settings.json turns on, and their GitHub proxy only serves the repositories attached to the session. So a plugin from a private marketplace doesn’t load there. Its skill still can. Zip the skill folder, upload it under Customize > Skills on claude.ai, and turn it on. In a new cloud session with nothing attached, it showed up as anthropic-skills:<skill>. The trade-offs: you upload again for every release, and the skill loads in every session on your account. A missing skill doesn’t raise an error. Claude still answers, but without the skill’s process, so ask the session to list its skills.

I was working on a project spread across several private repositories, and I created a skill I wanted to share between them as a Claude Code plugin. My plan was a private GitHub repository that’s both the plugin and its marketplace, so the skill stays in sync on my laptop and in cloud sessions. Most of my work happens in Claude Code on the web, because I like that it keeps the work off my laptop, runs in isolation, and is there on my phone. I tested the install commands by hand in a cloud session, then put them in the environment’s setup script, and the test worked. In the next real session the skill never loaded, and I got no error, not even a small one. Here’s how I tracked down the cause, what I tried that didn’t work, and the two workarounds that did.

Skill doesn’t load in a cloud session, and there’s no error

The session starts normally. You paste the notes the skill is built for, and Claude gives a reasonable, generic answer instead of following the skill.

That’s what makes it easy to miss. When a skill doesn’t load, Claude still answers, and nothing hints that a skill should have run. The only clue I had was that the answer was good but didn’t follow the skill’s steps.

My test had passed only because of how that session was set up. The session I tested in had the skills repository attached as one of its sources. The real sessions had only the repository I was working in. I also never confirmed that the saved setup script still had the install commands in it. Its log only showed output from another installer.

A second session found the cause. I messaged the failing session from the one where I built the plugin and asked it to inspect its own environment: the plugin list, the contents of ~/.claude, and the settings files. It reported that no marketplace had ever been added.

Cloud session can’t reach a private repository that isn’t attached

A cloud session reaches GitHub through a proxy, and the cloud environments documentation (opens in a new tab) says it serves GitHub API requests only for the repositories attached to the session. Git behaved the same way for me. In a fresh session with only the consuming repository attached, I tried to reach the skills repository:

$ git ls-remote https://github.com/<owner>/<skills-repo>.git

fatal: could not read Username for 'https://github.com': terminal prompts disabled

No credentials were supplied for it, so git asked for a username and gave up, even though the Claude GitHub App had access to that repository on my account. I didn’t run the same command against the attached repository to compare. The same session hit the limit again, this time with nothing to do with plugins: npm ci couldn’t fetch the project’s private SDK, which lives in another private repository that wasn’t attached.

Here’s what that means for each way of installing the plugin:

• Repository settings: The documentation (opens in a new tab) lists plugins and marketplaces declared in a repo’s .claude/settings.json as not available in cloud sessions. I never put the plugin there, so this is what the docs say, not something I tested.
• Setup-script install: I never confirmed my install commands ran, and the log was empty. If the script can only reach attached repositories, like the session, it had nothing to fetch. I haven’t tested that.
• Plugin installed mid-session: In one session, installing from an attached copy left the plugin enabled but not loaded, and the cloud UI has /reload-skills but no /reload-plugins. In an earlier session the same install did make the skill appear. I don’t know what was different.

Plugin added on claude.ai never reaches the session

Your claude.ai account has a plugins page too. Under Customize > Plugins > Add > Add marketplace > Add from a repository, claude.ai takes a private GitHub repository once the Claude GitHub App can read it. The plugins overview (opens in a new tab) says a plugin you add there downloads to Claude Code as a synced plugin, which the plugin loading reference (opens in a new tab) names <name>@synced. That reference says synced plugins load in Cowork and in signed-in terminal sessions. It doesn’t mention cloud sessions, although mine did get Anthropic’s synced plugins.

The marketplace synced and the plugin showed as added, with no error. In the ten minutes I watched, it never showed up anywhere:

• Cloud session, started five minutes after the add: The synced manifest under ~/.claude/plugins/synced/ listed 10 plugins, all from Anthropic’s knowledge-work-plugins marketplace. Mine wasn’t there.
• Terminal on my Mac, started ten minutes after the add: It printed Plugins changed. Run /reload-plugins to activate., and the rewritten manifest listed 4 plugins from the same Anthropic marketplace. Mine wasn’t there either.
• claude plugin marketplace list: Its From claude.ai: section listed only My Uploads and the Anthropic Directory.

One caveat: my Mac already had the same plugin installed from the command line, which may have affected that result. The cloud session had no local copy, so its result is clean. Add > Upload plugin is a second way to put a plugin on your account. I didn’t try it.

An open issue, anthropics/claude-code#92031 (opens in a new tab), describes the same thing from another account: plugins installed on claude.ai never reach cloud sessions, while skills enabled on the account do. That’s the route in the next section.

Upload the skill to your claude.ai account

A skill doesn’t need to be a plugin to reach a cloud session. The skills documentation (opens in a new tab) says cloud sessions load the skills enabled for your claude.ai account, synced at session start.

1. On your machine, zip the skill folder, with its SKILL.md inside the folder. To build the zip from a release tag in the skills repository, run:

   Command

   $ git archive --format=zip --prefix=<skill>/ -o <skill>.zip \
       <tag>:plugins/<plugin>/skills/<skill>

2. On claude.ai, go to Customize > Skills > Add > Upload skill, upload the zip, and turn the skill on.

3. Start a new cloud session, and ask Claude to list its skills.

On upload, claude.ai previews the skill’s name and description and runs a security scan. In a new cloud session with only the consuming repository attached, the skill showed up as anthropic-skills:<skill>. I checked that in one session. My test of Claude actually using the skill, in the section on confirming it loaded, ran on the copied version from the next section, which has the same files.

There are two costs. claude.ai numbers the skill’s versions v1, v2 and so on, not by your git tags, and each release means another upload. It’s an account skill, so it loads in every session on the account, not only the repositories that use it. That includes terminal sessions: on my Mac it appeared beside the same skill from the installed plugin, so the session offered it twice. Uninstall the local plugin, or turn the account skill off, to keep one.

Copy the skill into the cloud session

If a session needs a specific release, copy the skill in from the skills repository instead. The skills documentation (opens in a new tab) says Claude Code watches ~/.claude/skills/ and picks up a skill added there during the session, without a restart.

1. Start the cloud session with two repositories attached: the one you’re working in and the skills repository.

2. Ask Claude where the skills repository was cloned. It was /home/user/<skills-repo> in my sessions.

3. Ask Claude to copy the skill folder into your user skills directory, changing nothing else:

   Command

   $ mkdir -p ~/.claude/skills
   $ cp -R /home/user/<skills-repo>/plugins/<plugin>/skills/<skill> \
       ~/.claude/skills/<skill>

4. Ask Claude to list its skills. If ~/.claude/skills/ didn’t exist when the session started, run /reload-skills first, because Claude Code wasn’t watching it.

The skill loads as plain <skill>, with no prefix. To copy a specific release, run git -C /home/user/<skills-repo> fetch --tags and git -C /home/user/<skills-repo> checkout <tag> before the copy. I haven’t tested that step. The copy doesn’t carry over to other sessions.

If every session in a repository needs the skill, commit a copy under that repository’s .claude/skills/ instead. The documentation lists the repository’s own skills as available in cloud sessions. The cost is a copy in every repository, which is what the plugin was meant to avoid. I built it once, checked it against the release tag, and didn’t merge it.

Both routes bring over the plugin’s skills only. Hooks, agents and MCP servers in the plugin don’t load this way, and I haven’t found a way to load them in a cloud session without /reload-plugins.

Confirm the skill loaded

There are two checks. The session’s skill list shows the skill loaded. Asking a question the skill is built for, without naming the skill, shows that Claude actually uses it. My first test was a request to look over a project and say where it could be better. The session announced the skill’s first step and worked through its process. If the answer is generic, ask which skill it used.

For the skill list, ask Claude to list its skills, and look for <skill> or anthropic-skills:<skill>.

A plugin that shows as enabled in claude plugin list isn’t proof. In one of my sessions it was enabled and never loaded. A folder in ~/.claude/skills/ isn’t proof either, until the session lists it.

Do this with a coding agent

What found my cause was an agent inspecting its own environment. Paste this into the coding agent in the cloud session you want to check. Run it once in a session where the skill works and once where it doesn’t, then compare the two reports. Replace the placeholders first.

Inspect your own environment, read-only, and report whether a skill is available and where it came from. Change nothing: do not install, enable, disable, add, remove, copy, or edit anything, and do not print any token, key, or password you come across.

Skill name: <skill-name>
Plugin name: <plugin-name>
Skills repository: <owner>/<skills-repo>

1. Print the Claude Code version.
2. List the installed plugins with their version, scope, and status. Note which ones are <name>@synced.
3. List the plugin marketplaces that have been added.
4. List ~/.claude/skills/ and ~/.claude/plugins/, including plugins/synced/.
5. List the repositories attached to this session, and say whether the skills repository is one of them.
6. Run git ls-remote https://github.com/<owner>/<skills-repo>.git and quote any error verbatim.
7. Report whether this repository's .claude/settings.json has enabledPlugins or extraKnownMarketplaces entries.
8. Report whether a setup script log exists for this session and whether it contains output from a plugin install.
9. List the skills available to this session, and say whether <skill-name> is among them and under what name.

Then answer in this form:
- Skill <skill-name> available: yes or no, and under what name
- Plugin <plugin-name> installed: yes or no, and whether it is loaded or only enabled
- Synced plugins: the names, or none
- Skills repository attached: yes or no
- Skills repository reachable with git: yes, or the error
- Plugin settings in the repository: the entries, or none
- Setup script install output: found, not found, or no log
- Anything you could not check, and why

Common failures

Git fails with terminal prompts disabled

fatal: could not read Username for 'https://github.com': terminal prompts disabled

In a Claude Code cloud session, git prints this for a private repository that isn’t attached to the session, because the GitHub proxy supplies no credentials for it. A mistyped repository name probably produces the same prompt. Check the name, then attach the repository or start a session with it attached. The documentation describes the proxy’s answer to a GitHub API request for an unattached repository as a 403 whose message starts GitHub access to and contains is not enabled for this session.

Setup-script install leaves no trace

First check that the saved setup script still contains the install commands. Mine was never checked. If it does, a private skills repository that isn’t attached is a likely cause. The documentation (opens in a new tab) also says later sessions can start from a cached snapshot and skip the setup script, so a missing log line doesn’t prove the script failed. Check the session itself with claude plugin list.

enabledPlugins in .claude/settings.json does nothing in a cloud session

A cloud session doesn’t install the plugins a repository turns on under enabledPlugins. The plugin loading reference (opens in a new tab) says it doesn’t add the marketplaces under extraKnownMarketplaces either, because that needs the workspace trust dialog, which a cloud session never shows. Those keys still work for local sessions. The open issue anthropics/claude-code#78119 (opens in a new tab) tracks this, and a comment there reports that plugins declared in organization-managed settings don’t install in cloud sessions either. I can’t test that on an individual account.

Plugin is enabled but the skill isn’t listed

A plugin installed after the session starts loads only when Claude Code restarts or runs /reload-plugins, and the cloud UI has no /reload-plugins. Upload the skill to your claude.ai account, or copy it into ~/.claude/skills/.

Install worked in a test session and fails in the real one

What’s attached to a session decides what it can reach. Test in a session set up like the one that will use the skill, with the same repositories attached and nothing more.

Still open: a way to load a whole private plugin, with its hooks, agents and MCP servers, into a cloud session without attaching its repository. Its skills have a route. I haven’t found one for the rest. If you’ve found a way that works, I’d like to hear about it. Reply to any newsletter issue.

TL;DR

The camera didn’t stop recording. It restarted seconds later into a new drive folder that holds only the restarted cameras. Look for a folder named a few seconds after the broken one, with fewer than five cameras in it.

Don’t take the offset from the two folder names. Measure it by correlating the motion of two cameras that face the same way, such as the Gear Guard camera and the rear camera. Then re-encode the restarted cameras from the sibling folder at that offset, so that they start on the exact frame.

I cut a five-camera clip from a drive on August 7 and dropped it into a multicam timeline. Three angles played to the end. The rear camera and the side-left camera went black after 33 seconds. Every file was readable and nothing reported an error. The footage I thought was lost was in the next folder.

Rear or side camera stopped recording after a few seconds

The symptom has a few forms, depending on what you build from the drive:

• A camera’s only file in the drive folder is a few seconds long, while the other cameras have a full set of 15-minute segments.
• A multicam clip or a grid of the five cameras shows black tiles for one or two angles for most of the drive.
• A hyperlapse of one angle is much shorter than the others, or ends in black.

On the August 7 drive, the folder 08_07_26_140000 holds full segments for the front, Gear Guard and side-right cameras, and one 33-second file each for the rear and side-left cameras:

$ ffprobe -v error -show_entries format=duration -of csv=p=0 \
    08_07_26_140000/08_07_26_140000_rearCenter_001.mp4

33.000000

Cause: the camera restarted into a sibling folder

The truck writes one folder per drive, named MM_DD_YY_HHMMSS in local time, and one file per camera per 15-minute segment inside it. When a camera stops and restarts partway through a drive, its recording doesn’t continue in the drive’s folder. A new folder is created a few seconds later, and it holds only the cameras that restarted. The rest of the drive stays in the original folder.

The two folders together hold the whole drive. Nothing was lost, but the drive is now split across two clocks.

Find the sibling folder

Run this in the DriveStream folder of the truck’s drive, or of your copy of it. It prints each drive folder with the cameras it holds:

for d in */; do
  printf '%s ' "${d%/}"
  ls "$d" | grep -v '^\._' \
    | sed -E 's/^[0-9_]+_([A-Za-z]+)_[0-9]{3}\.mp4$/\1/' \
    | sort -u | tr '\n' ' '
  echo
done

The grep -v '^\._' drops the AppleDouble files that macOS leaves beside every clip on the truck’s exFAT drive. The August 7 folders look like this:

08_07_26_100000 frontCenter gearGuard rearCenter sideLeft sideRight
08_07_26_140000 frontCenter gearGuard rearCenter sideLeft sideRight
08_07_26_140034 rearCenter sideLeft
08_07_26_160000 frontCenter gearGuard rearCenter sideLeft sideRight

A sibling folder has all three of these properties:

• Its name is seconds, not minutes, after the previous folder’s name.
• It holds fewer than five cameras.
• Its cameras are the ones that stop early in the previous folder.

A short folder with one camera and no partner is a different case: a stray fragment, not half of a drive. Across 233 drive folders, one was a 21-second fragment from a single camera.

Folder name offset is wrong

The folder names differ by 34 seconds, so the obvious fix is to place the restarted cameras 34 seconds into the drive. Measured from the footage, the restarted cameras begin 32.7 seconds into the drive. The names are wrong by more than a second. The files’ creation_time tags are no better: the two folders' differ by 35 seconds, a third answer.

A folder name is a label, not a clock: nothing ties it to the first frame of the video inside. An error of more than a second is visible in a multicam edit. A car that passes the truck crosses the rear view and the side view at moments that no longer match. The truck’s files carry no timecode track to correct it, so the offset has to come from the pictures.

Measure the offset by motion correlation

Two cameras that see the same scene change at the same moments. When the truck hits a bump or a car passes behind it, both backward-facing pictures move at once. The script reduces each camera to a motion signal and slides one signal along the other until they match best:

1. Decode a window of each clip at a fixed sample rate, scaled to a tiny grayscale frame.
2. Take the mean absolute change between consecutive frames. That’s the motion signal: high when the picture changes, low when it holds still.
3. Standardize the reference, and each stretch of the other signal it’s compared with, so that a brighter or busier camera or stretch doesn’t outweigh the rest.
4. Try every lag within a search range around your guess, and keep the lag with the highest correlation.

It needs Python 3 and ffmpeg on your path, and nothing else:

"""Measure the time offset between two dashcam clips by correlating their motion.

Usage:
    python3 measure_offset.py REFERENCE OTHER --at SECONDS [--guess SECONDS]

Reads a window of REFERENCE starting at --at, and a slightly wider window of
OTHER around --at minus --guess. Prints the offset that lines the two up:
a moment at time t in REFERENCE is at time t - offset in OTHER.
"""
import argparse
import subprocess

WIDTH, HEIGHT = 32, 24
SAMPLES_PER_SECOND = 10


def motion(clip: str, start: float, seconds: float) -> list[float]:
    """Mean absolute change between consecutive tiny grayscale frames."""
    raw = subprocess.run(
        ["ffmpeg", "-nostdin", "-v", "error",
         "-ss", f"{start:.3f}", "-t", f"{seconds:.3f}", "-i", clip,
         "-vf", f"fps={SAMPLES_PER_SECOND},scale={WIDTH}:{HEIGHT},format=gray",
         "-f", "rawvideo", "-"],
        capture_output=True, check=True,
    ).stdout
    size = WIDTH * HEIGHT
    frames = [raw[i:i + size] for i in range(0, len(raw) - size + 1, size)]
    return [sum(abs(a - b) for a, b in zip(before, after)) / size
            for before, after in zip(frames, frames[1:])]


def standardize(values: list[float]) -> list[float]:
    mean = sum(values) / len(values)
    variance = sum((v - mean) ** 2 for v in values) / len(values)
    spread = variance ** 0.5 or 1.0
    return [(v - mean) / spread for v in values]


def best_lag(reference: list[float], other: list[float]) -> tuple[float, int]:
    """Slide reference along other; return the best correlation and its lag."""
    scores = []
    for lag in range(len(other) - len(reference) + 1):
        window = standardize(other[lag:lag + len(reference)])
        score = sum(a * b for a, b in zip(reference, window)) / len(reference)
        scores.append((score, lag))
    return max(scores)


def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("reference")
    parser.add_argument("other")
    parser.add_argument("--at", type=float, required=True,
                        help="window start in REFERENCE, seconds")
    parser.add_argument("--guess", type=float, default=0.0,
                        help="expected offset, seconds")
    parser.add_argument("--length", type=float, default=120.0,
                        help="window length, seconds")
    parser.add_argument("--search", type=float, default=5.0,
                        help="how far either side of the guess to look")
    args = parser.parse_args()

    reference = standardize(motion(args.reference, args.at, args.length))
    # The other window starts --search seconds early, so lag 0 means guess + search.
    other_start = args.at - args.guess - args.search
    other_length = args.length + 2 * args.search
    other = motion(args.other, other_start, other_length)

    score, lag = best_lag(reference, other)
    offset = args.guess + args.search - lag / SAMPLES_PER_SECOND
    print(f"window at {args.at:g} s: correlation {score:.2f}, offset {offset:+.1f} s")


if __name__ == "__main__":
    main()

Give it a camera from the original folder as the reference, a camera from the sibling folder as the other, and the folder-name difference as the guess. Both folders number their segments from 001 and every segment but the last runs 900 seconds, so segment 002 of the sibling starts the same offset after segment 002 of the original. Compare files with the same segment number, and keep the window inside one segment.

In the DriveStream folder, run:

$ python3 measure_offset.py \
    08_07_26_140000/08_07_26_140000_gearGuard_001.mp4 \
    08_07_26_140034/08_07_26_140034_rearCenter_001.mp4 \
    --at 300 --guess 34

window at 300 s: correlation 0.84, offset +32.6 s

One window is one measurement. Repeat it in windows that don’t overlap, from different segments, and trust the offset only when they agree. Four windows on the August 7 drive gave this:

That’s 32.7 seconds, plus or minus 0.1, from four independent windows. A moment at time t in the original folder is at t − 32.7 in the sibling folder.

Compare cameras that face the same way

The front camera was my first choice for the reference, because it recorded the whole drive. Against the restarted rear camera it gave two answers:

The two windows disagree by 0.9 seconds, and each one looks plausible on its own. The front camera sees the road ahead and the rear camera sees the road behind. Their pictures change for different reasons most of the time, so the best match moves from one window to the next. The Gear Guard camera looks backward over the bed, the same direction as the rear camera, and the two agree.

Pick a reference camera that kept recording in the original folder and faces the same direction as one of the restarted cameras. The files in a sibling folder share one start time and the same segment lengths, so the offset you measure for one of its cameras applies to all of them.

Stitch the restarted cameras

A stream copy can only start on a keyframe, and the truck writes one keyframe per second. The stream-copied angles from the original folder start on their own keyframes. An offset of 32.7 seconds isn’t a whole number of seconds, so no keyframe in the sibling folder falls on the same instant. Re-encode only the restarted cameras, cut at the exact frame, and leave the rest as stream copies.

Suppose your clip covers START to END seconds of the original folder, and OFFSET is the measured offset. The window has to begin after the restart, so START is greater than OFFSET. In the sibling folder, the clip begins at START minus OFFSET and lasts END minus START seconds.

In the DriveStream folder, the following commands write a concat list of the restarted camera’s segments in the sibling folder, and then cut the clip from the joined segments, re-encoding to HEVC. They create two files and change nothing in the drive folders:

printf "file '%s'\n" "$PWD"/08_07_26_140034/08_07_26_140034_rearCenter_*.mp4 \
  > rearCenter.txt
ffmpeg -f concat -safe 0 -i rearCenter.txt -ss <sibling-start> -t <duration> \
  -c:v hevc_videotoolbox -q:v 80 -tag:v hvc1 -color_range pc -an \
  <clip-folder>/rearCenter.mp4

Run the same two commands for every other camera in the sibling folder.

-ss after -i decodes from the start of the list and discards frames up to the exact time, so the output starts on that instant rather than on the nearest keyframe. It’s slow for a window late in the drive, because ffmpeg decodes everything before the window first. Joining the segments in one concat pass, rather than cutting each file and joining the cuts, keeps the frames whose group of pictures runs across a segment boundary. Cut multi-camera dashcam clips with ffmpeg covers the stream-copied cameras and that join in full.

The encoder hevc_videotoolbox is the hardware HEVC encoder on macOS. On another system, use the encoder you’d use for the rest of the project. The option -color_range pc labels the re-encoded angle full range like the truck’s footage, so it matches the stream-copied ones; check it with ffprobe -show_entries stream=color_range. The truck records no audio, so -an drops nothing.

Every file now starts at time 0. The re-encoded angles start on the exact frame, and a stream-copied one starts early by the lead the cut script printed for it. In DaVinci Resolve, mark each lead as an In point, then create the multicam clip with angle sync set to the In point.

Confirm the stitch

Run the same script on the finished clip, with the guess left at zero. In the clip’s folder, compare the Gear Guard camera, which was stream-copied from the original folder, with the re-encoded rear camera:

$ python3 measure_offset.py 08_07_26_140000_gearGuard.mp4 \
    08_07_26_140000_rearCenter.mp4 --at 300 --length 90

window at 300 s: correlation 0.79, offset +0.1 s

An offset of +0.1 seconds is one sample step of SAMPLES_PER_SECOND, the resolution of the method. The angles are in sync. The same script reported 32.7 seconds on the unstitched folders, so it does notice an offset when one exists. A zero from a check that has never reported anything else proves nothing.

TL;DR

PSScriptAnalyzer’s PSPossibleIncorrectComparisonWithNull rule is right for most code. When the left side of -ne is an array, PowerShell filters the array instead of returning true or false. These two tests ask different questions:

# Does $items hold at least one item that is not null?
if ($items -ne $null) { 'has items' }

# Is the variable itself something other than null?
if ($null -ne $items) { 'not null' }

An empty array fails the first test and passes the second. If the code you are cleaning up relies on the first, state that meaning in a form the analyzer accepts. It differs in one case: when the filter leaves exactly one item and that item is falsy, such as 0, '', $false or an empty array. That case is covered below:

function Test-HasItem {
    param($Value)
    @($Value | Where-Object { $null -ne $_ }).Count -gt 0
}

if (Test-HasItem $items) { 'has items' }

I ran into this cleaning up old PowerShell that someone else wrote. The plan was mechanical: run PSScriptAnalyzer and take its suggestions one at a time. One of them came from the rule PSPossibleIncorrectComparisonWithNull:

$null should be on the left side of equality comparisons.

I flipped the comparisons, and the warning went away. So did part of what the function did. The original author had written $array -ne $null on purpose, and the function depended on the behavior that the rule exists to warn about.

That’s why I wanted to write it up. Nothing here is a PowerShell bug, and the rule gives good advice for most code. This code was the exception: the author meant what they wrote, and fixing it broke it.

Reproduce the difference

In Windows PowerShell 5.1 or PowerShell 7, run:

PS> $values = @()
PS> if ($values -ne $null) { 'has values' } else { 'nothing to add' }

nothing to add

PS> if ($null -ne $values) { 'has values' } else { 'nothing to add' }

has values

The same variable, compared with the same operator, gives opposite answers.

Why the two comparisons disagree

An equality or matching operator with a collection on its left filters the collection. It returns every item for which the comparison is true, as an array. about_Comparison_Operators (opens in a new tab) documents this for every equality and matching operator.

So @() -ne $null returns an empty array, and if converts an empty array to $false. $null -ne @() has a scalar on the left, so it compares once and returns $true, because an empty array isn’t $null.

That’s why the analyzer asks for $null on the left: most code that writes $x -ne $null means “is $x null?”, and gets a filter instead when $x happens to be an array. The rule’s own documentation (opens in a new tab) says the same. The rule is correct about that code. It can’t tell that somebody’s code wanted the filter.

The filter has a second property, which matters later. if treats an array that holds exactly one item as that item. @(0) -ne $null returns @(0), and if (@(0)) is $false because 0 is.

What the original code meant

The function built combinations. Each call took the rows built so far and a set of values, and appended every value to every row. The two comparisons that the analyzer flagged are highlighted:

function Add-ToAll {
    param(
        [Parameter(Mandatory)] $currentResult,
        [Parameter(Mandatory)] $valuesToAdd
    )

    $returnValue = @()
    if ($valuesToAdd -ne $null) {
        foreach ($value in $valuesToAdd) {
            if ($currentResult -ne $null) {
                foreach ($result in $currentResult) {
                    $newResult = @($result)
                    $newResult += ,$value
                    $returnValue += ,$newResult
                }
            }
            else {
                $returnValue += ,@(,$value)
            }
        }
    }
    else {
        $returnValue = $currentResult
    }
    return ,$returnValue
}

Both comparisons use the filter on purpose:

• $valuesToAdd -ne $null is false for an empty array, so there’s nothing to add and the rows come back unchanged.
• $currentResult -ne $null is false for an empty array, so there are no rows yet and each value starts one.

The first call passes @() as $currentResult to start the chain. With the operands flipped, $null -ne @() is true, the inner loop runs over nothing, and the first call returns an empty array. Every later call appends to no rows and also returns nothing.

Each version, run on the same inputs, with its result as JSON:

Two rows still agree: both inputs empty, and the ordinary case, a real value added to rows that exist. A test suite built from typical inputs passes, and the change surfaces in production, on the first empty input.

Pin the current behavior in a Pester test

The analyzer’s fix looked safe because nothing checked what the function returned. Before you change inherited code, write a characterization test: run the current code on chosen inputs and assert what it returns now, whether or not that looks right. A refactor then has to keep every answer or change one on purpose.

This test for Pester 5, the PowerShell test framework, turns the earlier table into cases. Save the function as Add-ToAll.ps1 in the same folder:

BeforeAll {
    . $PSScriptRoot/Add-ToAll.ps1
}

Describe 'Add-ToAll' {
    It '<Name>' -TestCases @(
        @{ Name = 'both empty'; Json = '[]'
           Rows = @(); Values = @() }
        @{ Name = 'start from empty'; Json = '[["A"],["B"]]'
           Rows = @(); Values = @('A', 'B') }
        @{ Name = 'nothing to add'; Json = '[["X"],["Y"]]'
           Rows = @(@('X'), @('Y')); Values = @() }
        @{ Name = 'add null'; Json = '[["X"],["Y"]]'
           Rows = @(@('X'), @('Y')); Values = @($null) }
        @{ Name = 'one value'; Json = '[["X","A"]]'
           Rows = @(,@('X')); Values = 'A' }
        @{ Name = 'a single zero'; Json = '[["X"],["Y"]]'
           Rows = @(@('X'), @('Y')); Values = @(0) }
    ) {
        $result = Add-ToAll -currentResult $Rows -valuesToAdd $Values
        ConvertTo-Json -InputObject $result -Compress | Should -Be $Json
    }
}

The cases that matter are the ones the old comparison treated specially: an empty array, an array of nulls and a single falsy value. They are where a flipped comparison changes the result, and they are the inputs a typical test suite leaves out.

Run Invoke-Pester ./Add-ToAll.Tests.ps1 before you touch the function. Every case passes, because each expected value was copied from the original’s output. Flip the two comparisons and four cases fail: start from empty, nothing to add, add null and a single zero.

Each case compares JSON text instead of the array itself. Pass the result to ConvertTo-Json with -InputObject, not through the pipeline:

PS> @(,@('X','A')) | ConvertTo-Json -Compress

["X","A"]

PS> @('X','A') | ConvertTo-Json -Compress

["X","A"]

PS> ConvertTo-Json -InputObject @(,@('X','A')) -Compress

[["X","A"]]

PS> ConvertTo-Json -InputObject @('X','A') -Compress

["X","A"]

That output is PowerShell 7. Windows PowerShell 5.1 prints the first line as {"value":["X","A"],"Count":2}, which is one more reason to use -InputObject.

The pipeline sends the items of an array, not the array, and that loses information in two ways:

• A result with one row loses a level of nesting. One row, [["X","A"]], and a flat row, ["X","A"], serialize to the same text, so a refactor that returned the wrong shape would pass.
• An empty result sends nothing, so ConvertTo-Json writes nothing. With -InputObject, the same result is written as [].

When you write the cases, two inputs look different and are not:

• @(@()) is an empty array, not an array that holds one empty array. The array subexpression operator does not nest. Write ,@() for the nested one.
• @(@('X')) is @('X'), for the same reason. Write @(,@('X')).

Make the intent explicit

Replace each filtering comparison with a test that says what it checks. Keep the function’s structure and change only the two conditions:

# True when $Value holds at least one item that is not null. An empty array
# and an array of nulls hold none, which is what `$Value -ne $null` tested.
function Test-HasItem {
    param($Value)
    @($Value | Where-Object { $null -ne $_ }).Count -gt 0
}

if (Test-HasItem $valuesToAdd) {
    foreach ($value in $valuesToAdd) {
        if (Test-HasItem $currentResult) {

PSScriptAnalyzer reports nothing for this version. Run the test again and one case fails: a single zero. Given @(0), the explicit version returns [["X",0],["Y",0]], and the original returned the rows unchanged.

The original treated @(0) as nothing to add, because an array with one item converts to that item and 0 is false. The same is true of @(''), @($false) and @(,@()), an array holding one empty array, and of any input the filter reduces to one such item, such as @($null, 0). That is the one-item rule from earlier, not a decision anyone made, and the explicit version drops it. If your data can contain a single zero, empty string, $false or empty array, decide which behavior is correct. Change that case’s expected value only if the new behavior is the one you want.

Common failures

The warning is on -eq, not -ne. The same filter applies. @($null, $null) -eq $null returns two nulls, and an array with two items is true in an if, even though both items are null.

The left side is never an array. Then flipping the comparison changes nothing, and it guards against the day it becomes one. Check where the value comes from: a cmdlet that returns one object returns it bare, and one that returns several returns an array.

You want to keep the old line and silence the rule. Suppress it on that function with a reason, so the next person reads why:

[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
    'PSPossibleIncorrectComparisonWithNull', '',
    Justification = 'Empty array means nothing to add.')]

The attribute goes above the function’s param() block. The explicit test is still the better fix, because the reason then lives in the code rather than in a comment about it.

TL;DR

$LASTEXITCODE is not the success status of the last PowerShell cmdlet. Use it for a native executable such as aws.exe, and capture it immediately:

aws --version
$Code = $LASTEXITCODE
if ($Code -ne 0) { throw "AWS CLI exited with code $Code" }

For a cmdlet, use PowerShell error handling:

Get-Item -LiteralPath 'C:\Data\settings.json' -ErrorAction Stop

-ErrorAction Stop turns a cmdlet’s non-terminating error into a terminating one, which stops the script or reaches an enclosing catch.

While working on a backup script for my 7 Days to Die game server, I thought it would be good to share this.

You replace an AWS CLI command with a PowerShell cmdlet and keep the success check. The cmdlet prints an error. The script announces success anyway.

The check still runs. It’s reading the result of a different operation.

Reproduce a failed command with exit code zero

Run this in PowerShell on Windows:

cmd.exe /d /c exit 0
Write-Error 'Demonstration: the upload failed' -ErrorAction Continue
"Native exit code: $LASTEXITCODE"

The error appears, followed by:

Native exit code: 0

The zero came from cmd.exe. Write-Error did not update it. The explicit Continue makes this demonstration non-terminating even if your session normally uses a stricter error preference.

The reverse is just as misleading:

cmd.exe /d /c exit 7
Get-Date | Out-Null
"Native exit code: $LASTEXITCODE"

This prints 7 even though Get-Date succeeded. These examples illustrate why a value left in the variable is not evidence about a later cmdlet.

Microsoft defines the variable for native programs and PowerShell scripts; script behavior also depends on invocation and the exit keyword. Ordinary cmdlet success or failure does not make it a universal status register. See about_Automatic_Variables (opens in a new tab).

For native commands, check each result at the boundary

This example assumes AWS CLI is installed, the source exists, and the active AWS identity can access your chosen bucket:

$Source = 'C:\Data\exports'
$Destination = 's3://YOUR-BUCKET/exports/'

$null = Get-Command aws -CommandType Application -ErrorAction Stop
aws s3 sync $Source $Destination
$Code = $LASTEXITCODE

if ($Code -ne 0) {
    throw "S3 sync did not complete cleanly; AWS CLI exit code $Code"
}

'Export transfer completed'

Replace YOUR-BUCKET before running it. AWS documents nonzero outcomes including failed S3 transfers and skipped files. A skipped file is enough to reject a backup run as incomplete; inspect the command output for the cause. See the AWS CLI return-code reference (opens in a new tab).

Capture and handle each result before moving on.

Also distinguish a process failure from a launch failure. If aws is not found, no AWS CLI process returned an exit code, and the check reads whatever an earlier native command left. The Get-Command line stops the script before that can happen.

Why try/catch sometimes misses a cmdlet error

PowerShell can report an error while continuing execution. For example:

try {
    Write-Error 'Demonstration failure' -ErrorAction Continue
    'Still inside try'
}
catch {
    'Caught the error'
}

The error is displayed and Still inside try prints. The catch block isn’t entered. Change that one invocation to -ErrorAction Stop and the catch block runs instead.

Some errors already terminate execution; they don’t need this promotion. -ErrorAction Stop makes the intended behavior explicit for cmdlet errors that would otherwise continue. Microsoft’s try/catch documentation (opens in a new tab) explains which errors those blocks handle.

Catch a Write-S3Object failure with -ErrorAction Stop

With AWS.Tools.S3 installed and AWS access configured, use this for an intentional upload of one existing file:

Import-Module AWS.Tools.S3 -ErrorAction Stop

try {
    Write-S3Object -BucketName 'YOUR-BUCKET' `
        -File 'C:\Data\exports\report.json' `
        -Key 'exports/report.json' `
        -ErrorAction Stop

    'Upload completed'
}
catch {
    Write-Warning ("Upload failed: {0}" -f $_.Exception.Message)
    throw
}

The success message is reachable only after the upload returns normally. The bare throw propagates the caught error to the caller. Logging and then continuing would hide the failure from whatever invoked the script.

If you have no context to add and no recovery to attempt, remove the try/catch and keep -ErrorAction Stop. A catch block that only rethrows isn’t required.

$PSNativeCommandUseErrorActionPreference in PowerShell 7

PowerShell 7.4 added $PSNativeCommandUseErrorActionPreference. When it’s $true, nonzero native exit codes produce PowerShell errors governed by $ErrorActionPreference; with Stop, those can reach catch. The default is $false. Microsoft documents it in about_Preference_Variables (opens in a new tab).

That doesn’t make -ErrorAction Stop a parameter for aws.exe. Passed to a native program, it’s an argument for that program to interpret. Explicit exit-code checks remain useful for scripts spanning Windows PowerShell 5.1 and PowerShell 7, and for tools whose nonzero codes have special meanings.

If native error promotion is enabled with Stop, execution can leave the native invocation before the following explicit check. Either path must preserve the failure; don’t catch it and then print success.

Common failures

LASTEXITCODE is empty or stale. There may be no relevant native result in the session. Choose the error mechanism for the operation you actually ran.

Can I replace it with $? everywhere? $? describes the last command’s execution status and is overwritten by the next command. It isn’t a durable record of a multi-step job. Structured error handling is clearer for cmdlets.

The task still reports success. Check whether a wrapper catches and suppresses the error, then exits normally. At the outer script boundary, preserve a failure through an unhandled terminating error or an intentional nonzero exit code.

A script needs to remember whether the work succeeded. That starts by listening to the failure signal the command actually provides.

TL;DR

A batch label does not create a function body that cmd.exe skips. Execution runs straight through the label unless you redirect it.

Put the main work first, end it with exit /b, and place subroutines below it:

@echo off
setlocal EnableExtensions
call :timestamp
echo [%stamp%] Work starts here
exit /b 0

:timestamp
set "stamp=%DATE% %TIME%"
goto :eof

call :timestamp creates a return point. goto :eof returns from that call. Reached in the main batch context, it ends the batch instead.

You add a timestamp helper to a working batch file. The helper looks reasonable. The next run prints almost nothing, and the real work never starts.

It’s tempting to debug the timestamp expression. First check whether the script ever reaches the line that calls it.

Minimal reproduction: the call never happens

Save this as fall-through.cmd:

@echo off
echo Starting script

:timestamp
echo Inside timestamp
set "stamp=%DATE% %TIME%"
goto :eof

call :timestamp
echo [%stamp%] Doing the work

Run it from an existing Command Prompt so the output stays visible:

C:\scripts> cmd /d /e:on /c fall-through.cmd
Starting script
Inside timestamp

C:\scripts>

That output is the clue: the helper ran even though the call below it was never reached. Execution arrived there by reading downward.

A label marks a location. It doesn’t surround or hide the commands beneath it. The goto :eof then ends the current batch context, so both remaining lines are unreachable on this path. Microsoft’s goto reference (opens in a new tab) documents the special end-of-file target; you don’t need to define an :eof label.

End the main path with exit /b before the subroutines

Here is the complete repaired example:

@echo off
setlocal EnableExtensions

echo Starting script
call :timestamp
echo [%stamp%] Doing the work
exit /b 0

:timestamp
echo Inside timestamp
set "stamp=%DATE% %TIME%"
goto :eof

Expected output, with the timestamp varying by locale and clock:

Starting script
Inside timestamp
[<local date> <local time>] Doing the work

The main path calls the helper, resumes after the call, does its work, and exits before reaching the helper a second time. The helper is now reachable only through an intentional call.

Moving a subroutine to the bottom without the main-path exit is incomplete. The call returns correctly, but after the main work finishes, execution falls into the helper again.

What call, goto and exit /b each do

call :label starts a new batch context within the same file. When that context ends, execution resumes at the statement after the call. goto label only jumps; it doesn’t arrange a return. See Microsoft’s call reference (opens in a new tab).

The /b matters. exit /b ends the current batch context instead of cmd.exe, as Microsoft’s exit reference (opens in a new tab) says. A call :label runs in its own context, so inside a subroutine exit /b returns to the caller, and at the top level it ends the file. Use an explicit code when the caller needs a result.

These label-call and :eof examples assume command extensions are enabled, as they normally are. The repaired file makes that requirement explicit with setlocal EnableExtensions.

Helpers can also go above main

There’s no rule that subroutines must live at the bottom. If you prefer helpers first, jump over them on entry:

@echo off
setlocal EnableExtensions
goto main

:timestamp
set "stamp=%DATE% %TIME%"
goto :eof

:main
call :timestamp
echo [%stamp%] Doing the work
exit /b 0

Placement is a readability choice. An unambiguous execution path is the fix.

Common failures

The window disappears immediately. Run the file from an existing Command Prompt. A window opened only to run a batch file can close when that file ends; the disappearance alone doesn’t tell you which command caused it.

The helper runs twice. Look for a missing exit /b or goto :eof between the end of the main work and the first helper label.

The main work never resumes. Check for goto timestamp where you intended call :timestamp, or plain exit inside the helper.

I only needed a timestamp in a log. A separate subroutine may be unnecessary:

echo [%DATE% %TIME%] Backup started>>"backup.log"

This is a display timestamp, not a locale-independent filename format. Keep this simple example outside a parenthesized block, where percent-variable expansion introduces a separate timing issue.

When a batch file stops early, follow the lines it actually executes. A label that looks like a function declaration is still on that path.

TL;DR

When balenaEtcher stays at “Starting…” with no progress bar and no error, check the USB drive’s format. On a drive formatted as APFS, Etcher’s helper receives the write request and never starts writing. Running Etcher as sudo doesn’t change that. Erase the whole drive as exFAT and flash again.

The erase deletes everything on the drive. Replace N in diskN with the number diskutil list shows for your USB drive, and check it before the last command.

$ diskutil list
$ diskutil unmountDisk force /dev/diskN
$ diskutil eraseDisk ExFAT USB GPT /dev/diskN

If Etcher still stops, write the ISO with dd instead, as described in Create a bootable Linux USB drive on macOS with dd.

I wanted to repurpose my old Mac, a 2011 iMac, by putting Linux Mint on it. I wrote the installer USB drive on my Apple Silicon MacBook Pro with balenaEtcher. Etcher stopped at “Starting…” and gave no reason, so I wrote the drive with dd, and the iMac booted from it. Later I reproduced the hang on a second drive to find the cause.

Symptoms

balenaEtcher (also searched as Balena Etcher) detects the drive and loads the ISO. After you click Flash, the window stays at:

Starting...

No progress bar appears and no error is raised. Launching the app from a terminal with elevated permissions makes no difference:

sudo /Applications/balenaEtcher.app/Contents/MacOS/balenaEtcher

Etcher’s DevTools console shows the flasher starting and then stopping short of the write. This is Etcher 2.1.6 with an APFS-formatted drive:

Starting priviledged flasher sidecar on port 3435
/Applications/balenaEtcher.app/Contents/Resources/etcher-util
... with privileges ...
elevated pending
...
elevated granted
etcher-<id>
Connection to sidecar flasher process attempt 1 / 10 failed; retrying in 1000ms...
etcher-<id>
CHILD READY
start heartbeat
params Object
CHILD LOG: Ready ...
CHILD LOG: write requested
CHILD LOG: Image: /Users/<user>/Downloads/<image>.iso
CHILD LOG: Devices: /dev/diskN
CHILD LOG: Auto blockmapping: true
CHILD LOG: Decompress first: true

The log reaches write requested, echoes the job’s settings, and no bytes follow. In the log, <user> is your account name and <image> is the ISO you selected. N is your drive’s disk number, and <id> is a random name Etcher gives each helper run.

APFS drive that stops the helper before the write

Etcher doesn’t write the disk itself. The Electron app launches a separate privileged helper, the “sidecar flasher”, and hands it the image and the device. The CHILD LOG lines after write requested are the helper echoing that request back. Etcher asks macOS for administrator rights for the helper itself, which is what the elevated pending and elevated granted lines record, so sudo adds nothing. Run as sudo, the log is identical.

The log doesn’t show why the helper stops. The drive’s format does. I reproduced the hang with a second USB drive, a different ISO and Etcher 2.1.6, and changed only the format between two runs:

Erased as exFAT, the same flash continued straight into progress:

CHILD LOG: Decompress first: true
Flashing 1 device, 0% at 1.60 MB/s (total 1.60 MB/s) eta in 235s with 0 failed devices

That matches the reports on balena’s forums. One thread (opens in a new tab) states that Etcher doesn’t work on an APFS drive and surfaces no error. Another (opens in a new tab) with this hang was resolved by erasing the drive as exFAT.

A USB drive isn’t APFS unless someone made it so. Disk Utility offers APFS only when you erase the whole device with a GUID partition map, not when you erase a volume on a drive with the older MBR layout. I don’t know what the first drive was formatted as when it hung. dd wrote the Mint image to it without an error, so the ISO and the drive weren’t at fault.

Erase the USB drive as exFAT

The erase replaces the drive’s partition map and every volume on it. Copy off anything you need from the drive first.

1. Find the USB drive

$ diskutil list

Find the header that reads external, physical and matches your drive’s size. Its number replaces N in the next step. An APFS drive also appears a second time, as a synthesized container. Use the external, physical identifier, not the container’s.

2. Erase it

$ diskutil unmountDisk force /dev/diskN
$ diskutil eraseDisk ExFAT USB GPT /dev/diskN

force matters when Spotlight is indexing the drive. Without it, the erase can fail with Couldn't unmount disk. : (-69888) and name the process mds. USB is the new volume name; any name works, because the flash overwrites it.

3. Flash again

Select the ISO and the drive in Etcher, and click Flash. Within a few seconds, the window shows Flashing... with a percentage, and the DevTools log shows Flashing 1 device lines.

Write the ISO with dd instead

If Etcher still stops after the erase, dd writes the image without Etcher’s helper. That’s how the Mint drive in this article was written. The steps, the checks that keep dd off the wrong disk, and how to confirm the write are in Create a bootable Linux USB drive on macOS with dd.