pulumi/pulumi · error · Error

The Pulumi CLI does not support remote operations. Please up

Error message

The Pulumi CLI does not support remote operations. Please upgrade.

What it means

LocalWorkspace validates remote support by running `pulumi preview --help` and checking whether the `--remote` flag appears in the help output. When remote options are used (remote: true in StackSettings/LocalWorkspaceOptions) and the connected CLI does not advertise --remote, the SDK throws this error telling you to upgrade, because remote operations (SSI/pulumi deployments remote execution) require a sufficiently new CLI.

Source

Thrown at sdk/nodejs/automation/localWorkspace.ts:1107

    /**
     * A hook executed after every command. Called with the stack name. An
     * extensibility point to perform workspace cleanup (CLI operations may
     * create/modify a `Pulumi.stack.yaml`) {@link LocalWorkspace} does not
     * utilize this extensibility point.
     */
    async postCommandCallback(_: string): Promise<void> {
        return;
    }

    private async checkRemoteSupport() {
        const optOut = !!this.envVars[SKIP_VERSION_CHECK_VAR] || !!process.env[SKIP_VERSION_CHECK_VAR];
        // If remote was specified, ensure the CLI supports it.
        if (!optOut && this.isRemote) {
            // See if `--remote` is present in `pulumi preview --help`'s output.
            const previewResult = await this.runPulumiCmd(["preview", "--help"]);
            const previewOutput = previewResult.stdout.trim();
            if (!previewOutput.includes("--remote")) {
                throw new Error("The Pulumi CLI does not support remote operations. Please upgrade.");
            }
        }
    }

    private async runPulumiCmd(args: string[]): Promise<CommandResult> {
        let envs: { [key: string]: string } = {};
        if (this.pulumiHome) {
            envs["PULUMI_HOME"] = this.pulumiHome;
        }
        if (this.isRemote) {
            envs["PULUMI_EXPERIMENTAL"] = "true";
        }
        envs = { ...envs, ...this.envVars };
        return this.pulumiCommand.run(args, this.workDir, envs);
    }

    /**
     * @internal

View on GitHub (pinned to 793f7b2e16)

Solutions

  1. Upgrade the Pulumi CLI to a version supporting remote operations (latest)
  2. If remote support is not needed, remove `remote: true` from workspace/stack options
  3. Temporarily opt out of the remote check by setting the PULUMI_AUTOMATION_API_OPT_OUT_REMOTE environment variable (only if you know remote commands are unnecessary)

Example fix

// before
const stack = await LocalWorkspace.createOrSelectStack({
  stackName: "org/proj/stack",
  workDir: ".",
  remote: true,
}); // old CLI -> throws
// after
$ pulumi version
3.130.0 // upgrade CLI, then same code succeeds
Defensive patterns

Strategy: validation

Validate before calling

const help = await (stack.workspace as any).runPulumiCmd(["preview", "--help"]);
if (usingRemote && !help.stdout.includes("--remote")) {
  throw new Error("Remote operations require a newer Pulumi CLI");
}

Try / catch

try {
  const stack = await LocalWorkspace.createOrSelectStack(remoteOpts);
} catch (err) {
  if ((err as Error).message.includes("does not support remote operations")) {
    // prompt CLI upgrade or fall back to local execution
  } else throw err;
}

Prevention

When it happens

Trigger: Creating a LocalWorkspace/Stack with remote: true (or RemoteWorkspace/RemoteStack) while the CLI's `pulumi preview --help` output lacks `--remote`, typically CLI < 3.104 era; also when PULUMI_AUTOMATION_API_OPT_OUT_REMOTE is unset so the check runs.

Common situations: Using RemoteStack against an old self-installed CLI; containers with pre-remote CLIs; organizations that self-manage CLI versions and lag behind the SSI/remote features.

Related errors

AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/80abf9e4b723529d. Report an issue: GitHub.