pnpm ERR_PNPM_INVALID_PROXY: Fix Empty HTTP_PROXY and HTTPS_PROXY

Unset empty proxy variables before pnpm install#

On macOS, Linux, and other shells that provide env -u, run the install with the empty variables removed:

1
env -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
2
  -u http_proxy -u https_proxy -u all_proxy \
3
  pnpm install --frozen-lockfile

For a GitHub Actions step, unset the variables inside the shell that runs pnpm:

1
- name: Install dependencies
2
  shell: bash
3
  run: |
4
    unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
5
    unset http_proxy https_proxy all_proxy
6
    pnpm install --frozen-lockfile

Setting the variables to "" is not the same as removing them. An empty value can still be parsed as a proxy setting by an affected pnpm version.

In PowerShell, remove the process-level values before invoking pnpm:

1
$env:HTTP_PROXY = $null
2
$env:HTTPS_PROXY = $null
3
$env:ALL_PROXY = $null
4
pnpm install --frozen-lockfile

Do this only when the job is not supposed to use a corporate proxy. If the network requires one, configure a valid URL instead of unsetting it.

If a proxy is required, use a valid URL#

A proxy value needs a scheme and an address, for example:

1
export HTTPS_PROXY='http://build-user:p%[email protected]:8080'
2
pnpm install --frozen-lockfile

URL-encode reserved characters in the username or password. A raw @, #, %, or space can turn an otherwise correct credential into an invalid URL. Keep credentials in the CI secret store or the user-level configuration that your environment controls; do not commit them to a project .npmrc.

Inspect what pnpm sees without printing a secret-bearing configuration file:

1
pnpm config get proxy
2
pnpm config get https-proxy
3
pnpm config list

Then check the environment separately:

1
env | grep -iE '^(http|https|all)_proxy='

The command output is diagnostic data. Redact credentials before pasting it into an issue or CI log.

Understand the pnpm 12 status before changing every workflow#

The pnpm issue #13533 records the empty-proxy regression, including the ERR_PNPM_INVALID_PROXY symptom and the difference from pnpm 11 behavior. Pull request #13597 treats empty proxy values as unset and closes that issue.

That does not mean every runner has the repaired code. pnpm 12.0.0-rc.7 was released on August 18, 2026, while the visible release notes do not make the proxy fix easy to identify. Check the executable that actually runs in CI:

1
pnpm --version
2
command -v pnpm

If the version is an older beta or the error persists after an upgrade, keep the unset step until the image is updated and the install passes. Do not silently change the lockfile or the package manager version while diagnosing an environment-variable parse failure.

The pnpm .npmrc documentation is the right place to review project and user configuration. A project-level proxy setting is a different input from an environment variable, but both can affect the install boundary. Check the actual configuration locations used by the CI account.

Keep proxy cleanup separate from dependency failures#

Once the proxy error is gone, a later install failure may be unrelated. Keep these cases distinct:

• a registry authentication error means the registry or token boundary needs inspection;
• a Git dependency over SSH needs keys and a known-hosts setup, as covered in the pnpm Git dependency CI guide;
• a package install script blocked by pnpm policy is a lifecycle configuration issue, not a proxy URL issue. The pnpm build-script approval guide covers that boundary.

Run the same frozen install after the environment is corrected:

1
pnpm install --frozen-lockfile
2
pnpm audit --audit-level=high

The second command is optional and should follow the project’s normal security workflow; it is not evidence that the proxy was configured correctly.

The durable rule is to represent “no proxy” by an absent variable, not an empty URL. If a proxy is required, provide a complete URL, keep its credentials out of the repository, and verify the pnpm version inside the failing job before changing dependency files.

FAQ#