stablyai/orca · error · Error

Windows blocked updating your user PATH (access denied). Thi

Error message

Windows blocked updating your user PATH (access denied). This usually means your PATH environment variable is managed by Group Policy or your organization's device management. ${guidance}

What it means

Thrown by writeWindowsUserPathEntry when the PATH write is denied. isWindowsUserPathPermissionError detects .NET/ACL markers (UnauthorizedAccessException, SecurityException, 'Access is denied') in the error. The message explains that Group Policy or device management likely controls PATH and provides actionable guidance.

Source

Thrown at src/main/cli/cli-installer.ts:895

  // Why: raw PowerShell errors reach the UI, so translate denied PATH writes (keeping the original as cause).
  private async writeWindowsUserPathEntry(
    value: string,
    pathDirectory: string,
    action: 'add' | 'remove'
  ): Promise<void> {
    try {
      await this.userPathWriter(value)
      this.userPathCacheInvalidator()
    } catch (error) {
      if (!isWindowsUserPathPermissionError(error)) {
        throw error
      }
      const guidance =
        action === 'add'
          ? `Add this folder to your PATH manually: ${pathDirectory}. Or run Orca as an administrator and try again.`
          : `Remove this folder from your PATH manually: ${pathDirectory}. Or run Orca as an administrator and try again.`
      throw new Error(
        `Windows blocked updating your user PATH (access denied). This usually means your PATH environment variable is managed by Group Policy or your organization's device management. ${guidance}`,
        { cause: error }
      )
    }
  }
}

async function ensureDevLauncher(args: {
  platform: NodeJS.Platform
  userDataPath: string
  execPath: string
  cliEntryPath: string
  commandName: string
}): Promise<string | null> {
  if (
    !isAbsoluteForPlatform(args.platform, args.execPath) ||
    !isAbsolute(args.cliEntryPath) ||
    !existsSync(args.cliEntryPath)

View on GitHub (pinned to 1136503c6a)

Solutions

Manually add/remove the folder from PATH via Windows Settings > Environment Variables.
Run Orca as administrator and retry CLI registration.
Ask your IT admin to allow PATH modifications for your user account.
Use the bundled orca.exe path directly without PATH registration if admin access is unavailable.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await installer.ensureWindowsPathEntry(dir)
} catch (error) {
  if (error instanceof Error && error.message.includes('access denied')) {
    // Provide manual PATH instructions; suggest running as admin
    showManualPathInstructions(dir, action)
  } else { throw error }
}

Prevention

On managed Windows, provide manual PATH instructions as a fallback.
Detect Group Policy-managed environments early and skip automatic PATH writes.
Suggest running as administrator when permission errors are likely.

When it happens

Trigger: The userPathWriter (PowerShell [Environment]::SetEnvironmentVariable or registry write) throws an access-denied error. isWindowsUserPathPermissionError matches the error text against known permission-denied markers.

Common situations: Corporate-managed Windows where Group Policy locks HKCU\Environment. Device management software (Intune, etc.) restricts environment variable writes. Non-admin user on a locked-down machine. UAC preventing registry writes to certain keys.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/a9c6845d41b8b78f. Report an issue: GitHub.