[BUG] CLI shows low-level permission error when output directory is not writable

[sahillllllllll-bit]

Describe the bug.

When generating output to a directory without write permissions (for example /root/output), the AsyncAPI Generator fails with a low-level filesystem error (EACCES). The error message is not user-friendly and does not explain how to resolve the issue, such as choosing a writable directory or adjusting directory permissions.

Expected behavior

When the output directory is not writable, the CLI should display a clear, user-friendly error message explaining that permission is denied and suggesting actionable steps, such as using a directory with write access or adjusting permissions.

Screenshots

How to Reproduce

1. Prepare a valid AsyncAPI specification file (for example asyncapi.yaml).
2. Run the AsyncAPI Generator with an output directory that is not writable by the current user:

   asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o /root/output
   

3. Observe that the command fails with a low-level permission error.

🖥️ Device Information [optional]

• Operating System (OS) Windows (WSL)
• Browser: N/A
• Browser Version: N/A

👀 Have you checked for similar open issues?

• I checked and didn't find similar issue

🏢 Have you read the Contributing Guidelines?

• I have read the Contributing Guidelines

Are you willing to work on this issue ?

Yes I am willing to submit a PR!

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[dosubot]

Hi @sahillllllllll-bit! I'm Dosu and I’m helping the generator team.

You're right—when the output directory isn't writable, the CLI currently shows a raw Node.js permission error like EACCES: permission denied, mkdir ... without any user-friendly explanation or actionable advice. This happens because the directory creation logic (using xfs.mkdirpSync in the Generator class and xfs.mkdirp in the CLI) just throws or passes the error up, and the CLI prints it as-is via showErrorAndExit without checking for permission issues or rewording the message. There isn't any utility or pattern in the codebase for translating these errors into something more helpful for users yet source.

To improve this, you could enhance the CLI error handling (where showErrorAndExit is called) to check if the error is a permission error (e.g., err.code === 'EACCES') and display a clearer message, like:

Permission denied: Cannot write to the output directory.
Please choose a directory you have write access to, or adjust the permissions for the target directory.

Here's a quick example of how you might implement this in the CLI:

function showError(err) {
  if (err.code === 'EACCES') {
    console.error(red('Permission denied: Cannot write to the output directory.'));
    console.error(red('Please choose a directory you have write access to, or adjust the permissions for the target directory.'));
  } else {
    console.error(red('Something went wrong:'));
    console.error(red(err.stack || err.message));
  }
  if (err.diagnostics) {
    // existing diagnostics printing
  }
}

This approach is consistent with how other user-facing errors are handled elsewhere in the codebase (like unsupported languages or protocols), and would make the CLI much more user-friendly for this common scenario source.

No recent PRs or docs address this yet, so your contribution would fill a real gap!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[sahillllllllll-bit]

Hi @dosu

Thanks for the analysis @dosu — I agree that improving the error message for permission issues would make the CLI much more user-friendly.

I’d like to work on this issue and submit a PR with the suggested improvement (better EACCES handling + clear message).

I’ll try to follow the approach you described and also add a small test case if possible.
would i submit pr ?
Thanks!

[dosubot]

Absolutely, you’re welcome to submit a PR for this improvement! Your plan to enhance EACCES error handling and add a user-friendly message is spot on and aligns with what maintainers want to see. Including a small test case is a great idea—if you’re able to simulate a permission error in a test (for example, by mocking the fs module or using a temp unwritable directory), that will make your PR even stronger.

Just follow the contributing guidelines and reference the approach we discussed. The maintainers appreciate contributions that improve the CLI experience and will review your PR through the usual process.

If you run into any issues or have questions while working on the PR, feel free to ask!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[sahillllllllll-bit]

@dosu Thanks for the detailed explanation and guidance.

I’ve tested the change locally and opened a PR.
Could you please take a look and let me know if this approach aligns with the maintainers’ expectations?

[dosubot]

Your approach to improving EACCES error handling and providing a user-friendly message in the CLI is exactly what maintainers are looking for. The project has a history of user reports and maintainer discussions about permission errors and the need for clearer, actionable error messages when the output directory isn't writable. Your solution aligns with these expectations and fills a real gap in the current experience.

As you finalize your PR, make sure it follows the project's contribution guidelines: use a clear, Conventional Commits-style title, reference the related issue in the description, and include a meaningful test case if possible. Maintain good code style and documentation, and ensure your error message is clear and actionable—something like: "Permission denied: Cannot write to the output directory. Please choose a directory you have write access to, or adjust the permissions for the target directory." This matches both user and maintainer feedback on what would be most helpful in these scenarios see discussion.

If your PR covers these points, it should align well with maintainer expectations!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}