Skip to content

maxrave-dev/kotlin-footguns / skills/desktop-and-build-footguns

desktop-and-build-footguns

Verified

Desktop JVM and build traps: JNA natives, bundling, memory, packaging, code signing, R8, deep links, Gradle and CI releases. Use when a desktop build fails packaged, signed, on another OS or arch, or in CI.

references/macos-lsenvironment-path-pin.md

View on GitHub
---
name: macos-lsenvironment-path-pin
description: Declaring a Launch Services environment dictionary (`LSEnvironment`) in a packaged macOS app's property list pins the process `PATH` to the four bare system directories, so every external process the app spawns loses everything installed elsewhere. Use before adding any environment variable to a macOS app bundle, when a helper the app shells out to reports "command not found" only for installed users, or when a feature that works from a terminal launch silently does nothing from the Dock.
---

# The environment dictionary pins `PATH`

A packaged macOS app can carry environment variables in its property list under `LSEnvironment` —
the **Launch Services** environment dictionary. It is the normal way to set an allocator flag, a
runtime toggle or a debug switch for a shipped app.

It has one side effect that is easy to miss and expensive to find:

> **Declaring the dictionary at all pins the process `PATH` to `/usr/bin:/bin:/usr/sbin:/sbin`.**

Not any particular key — the presence of the dictionary. Anything the app then starts as an
external process sees only those four directories. Tools installed by a package manager, in the
user's home, or anywhere under `/usr/local` are simply not found.

Two properties of the dictionary decide when it applies:

- It is applied by **Launch Services**, so it covers file-manager, Dock, Spotlight and `open`
  launches — every normal launch of an installed app.
- It is **not** applied when you run `Contents/MacOS/<binary>` directly from a shell. That
  invocation inherits your shell environment instead.

Which means: **you cannot reproduce this from a terminal.** The way you test a desktop app during
development is precisely the launch path that does not have the pin.

```hocon
# adapted — packaging config, macOS section
mac {
  # Declaring this dict pins PATH to /usr/bin:/bin:/usr/sbin:/sbin.
  # Audited before adding — see the note in the audit section below.
  info-plist.LSEnvironment.<KEY> = "<value>"
}
```

## Traps

**The audit is a precondition, not a follow-up.** Before adding the key, find every external
process the app can start on the macOS path and record, for each, why it is safe. That note is
the artefact — it is what stops the next person redoing the audit, and what tells them when the
answer has changed.

**Platform-gated spawns still belong in the audit.** In the case above the only spawn on the
macOS code path was a probe gated to another OS, so the answer was "unreachable here". Write that
down rather than leaving the call site unexplained; a later change that removes the gate is
otherwise invisible.

**Some platform APIs never consult `PATH`, and flagging them wastes the audit.** Opening a URL or
a file through the desktop-integration API goes through Launch Services, which resolves the
handler without `PATH`. Those hits are false positives — but only if you have confirmed the call
really goes through that API and not through a spawned launcher command as a fallback. A
per-OS fallback chain that shells out is exactly the kind of code that gets added later.

**The symptom does not name `PATH`.** It arrives as "command not found" from a helper, a feature
that quietly does nothing, or a launch that fails only for users who installed the app normally.
If the spawn failure is swallowed — a `runCatching` with no log — there is no symptom at all,
just a dead feature.

**Removing the key is the wrong rollback if you still want its effect.** Dropping the dictionary
restores normal `PATH` inheritance and loses whatever you added it for. Prefer adding `PATH`
explicitly to the same dictionary, with the directories your helpers actually live in appended to
the four bare ones.

**Absolute paths are the durable fix.** For anything you ship or can locate deterministically,
spawn it by absolute path or pass an explicit environment to the process builder, so the app does
not depend on `PATH` at all. Then the pin costs nothing.

**This is macOS-specific.** The Windows and Linux packaging paths have their own environment
mechanisms with their own rules; do not carry this conclusion across.

## Verifying it

1. **Find every spawn site** and record a verdict for each:

   ```bash
   grep -rn "ProcessBuilder\|Runtime.getRuntime().exec\|exec(" \
     --include='*.kt' --include='*.java' <src>
   ```

2. **Resolve each command on a clean machine** — `command -v <tool>` — and check the answer is
   inside `/usr/bin`, `/bin`, `/usr/sbin` or `/sbin`. Anything else will not be found once the
   dictionary is declared.

3. **Confirm the key reached the packaged app.** Read the property list out of the built bundle
   rather than trusting the packaging config; a key written at the wrong nesting level is
   accepted silently by many config formats and never appears in the output.

4. **Test from the file manager, not the terminal.** Launch the installed app the way a user
   would, then print the running process's environment (`ps eww -p <pid>`) and confirm both that
   your variable is present and what `PATH` became.

5. **Re-run step 1 whenever a feature adds an external process**, and keep the audit note beside
   the config key so the connection is discoverable from either end.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 323kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 323kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 323kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 323kUpdated Claude CodeCodexVerifiedInstall