asyncapi / asyncapi/cli

[BUG] Windows Installer (.exe) Fails due to MAX_PATH limitations

Open
#2,248 4 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
TypeScript
Stars
272
Forks
375
Avg merge
3h 22m
Merged PRs (30d)
8

Description

### Describe the bug.

The AsyncAPI CLI installer (`.exe`) generated via `oclif pack win` consistently fails to install on Windows machines. The process terminates prematurely with an `Error opening file for writing`, specifically when attempting to extract files within the `node_modules` directory. I believe this is caused by *path length*, which is exceeding the Windows 260-character `MAX_PATH` limit.

## Deep Dive
The issue appears to be between the current packaging toolchain and the project's dependency graph. Specifically:
* **Deep Dependency Nesting:** Components such as `@asyncapi/studio` and their internal standalone builds generate significantly nested `node_modules` trees.
* **Packaging Toolchain Limitations:** `oclif pack win` bundles the physical `node_modules` structure as-is. It does not perform the dependency hoisting or path optimization required to flatten these trees during the packing process.
* **OS Constraints:** Because the resulting installer contains paths exceeding 260 characters, the Windows NSIS extraction process fails, rendering the CLI un-installable on Windows environments.

## Investigation Summary
I conducted a local investigation to ascertain whether this was a configuration issue or a system level limitation. My attempts to remediate included:

| Attempt | Method | Outcome |
| :--- | :--- | :--- |
| **Dependency Hoisting** | Used `pnpm --config.node-linker=hoisted` | Flattened the root `node_modules`, but the `oclif` packer completely ignored the flattened hoisted `node_modules` directory when it compiled the `.exe`. |
| **Clean NPM Build** | Executed `npm install --legacy-peer-deps` | Produced a valid binary, but internal sub-dependency nesting persisted, maintaining the `MAX_PATH` violation. |
| **Manual Resolution** | Installed missing peer dependencies & bypassed security scripts | Forced a successful local build, yet the resulting installer still failed on Windows due to the same path length violations in the `@asyncapi/studio` build tree. |

The persistence of this issue despite my trials to resolve it, suggests that the current packaging toolchain is not suited for the project's current dependency on Windows.

## Supporting Evidence
The installation consistently fails at this specific path:
`...\node_modules\@asyncapi\studio\build\standalone\node_modules\.pnpm\next@...`
(It happened with multiple files during extraction phase which forced me to abort the installation)

## Proposed Path Forward
Given these findings, I believe the current strategy of distributing a single bundled `.exe` via `oclif` is becoming problematic for the CLI's dependency graph on Windows.

I would appreciate guidance from the core team on whether there is an interest in evaluating alternative packaging strategies, or if there is a preferred way to refactor the build stage to resolve this bug. I'll be glad to help.

**NOTE:** This bug is reported in this **[ISSUE](https://github.com/asyncapi/cli/issues/2239)** , But not in such detail as proposed here.

### Expected behavior

Finishes setup without any errors.

### Screenshots

Image

>

### How to Reproduce

1. Download the CLI for Windows ( `asyncapi.x64.exe`) from the [Release Page](https://github.com/asyncapi/cli/releases)
2. Run the installer

### 🖥️ Device Information [optional]

- Operating System (OS): Windows 11

### 🏢 Have you read the Contributing Guidelines?

- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the Windows installer failure from the release page with `oclif pack win` and inspect how the command packages the physical node_modules tree. Compare the generated paths with the failing @asyncapi/studio standalone path; done means the Windows installer completes setup without a MAX_PATH extraction error.

Written by the indexing model from the issue text.

Assessment

Tech stack
nodejs, typescript
Domain
build-system, cli, operating-systems
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.