You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by "bettermultiply (via GitHub)" <gi...@apache.org> on 2025/11/30 15:39:38 UTC
[I] Docs improve: make the README of core/examples easier for newbie [opendal]
bettermultiply opened a new issue, #6838:
URL: https://github.com/apache/opendal/issues/6838
Please forgive my rudeness, I am just try to figure out what opendal is and how to use it.
When I try to follow the core/examples/README.md to start my opendal journey, and change the `.env.examples` as told. However, it told me:
```
thread 'main' (270135) panicked at src/raw/tests/utils.rs:72:46:
must succeed: Unexpected (permanent) at Builder::build => create atomic write dir failed
Context:
atomic_write_dir: /path/to/dir
Source:
Permission denied (os error 13)
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```
And it takes me some time to figure out that there are more need to be changed in `.env` file. (Of course, the log is comprehensive and the root cause is my madness)
I believe that if we can make README more complete, newbie(like me) will have more confidence to dive into opendal. =)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@opendal.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Docs improve: make the README of core/examples easier for newbie [opendal]
Posted by "dosubot[bot] (via GitHub)" <gi...@apache.org>.
dosubot[bot] commented on issue #6838:
URL: https://github.com/apache/opendal/issues/6838#issuecomment-3592712026
<!-- Greeting -->
Hi @bettermultiply! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the opendal team.
<!-- Answer -->
You're absolutely right—many new users run into similar issues with the examples, especially around the .env setup and directory permissions. The "Permission denied (os error 13)" error usually means the process doesn't have write access to the directory specified by environment variables like OPENDAL_FS_ROOT or atomic_write_dir, or that the directory doesn't exist yet. This is a common stumbling block and has come up in several user reports and issues before ([example](https://github.com/apache/opendal/issues/5781), [example](https://github.com/apache/opendal/issues/5639), [example](https://github.com/apache/opendal/issues/4867)).
To make the README more newbie-friendly, it would help to:
- Add step-by-step instructions for copying and editing the .env file, including which variables must be set for each example.
- Explicitly mention that directories like OPENDAL_FS_ROOT and atomic_write_dir must exist and be writable by the user running the example.
- Include a troubleshooting section for common errors like "Permission denied" or "root is not specified", with tips on how to fix them (e.g., `mkdir -p /path/to/dir && chmod u+w /path/to/dir`).
- Clarify that some services (like HDFS) may require extra environment variables or system configuration.
Your feedback matches what others have experienced, and maintainers have discussed moving examples and improving docs to make onboarding smoother for everyone ([see here](https://github.com/apache/opendal/issues/2446)). If you have specific suggestions or wording that helped you, sharing those would be valuable for making the docs even better!
<!-- Dosu Comment Footer -->
*To reply, just mention [@dosu](https://go.dosu.dev/dosubot).*
---
<sup>How did I do? [Good](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/d33948b2-08f8-4cf6-9a86-d02edfdf92f6?feedback_type=other)</sup>
[](https://app.dosu.dev/997a2c5a-0c54-497b-989d-44651635dd36/ask?utm_source=github) [](https://cursor.com/link/prompt?text=You%27re%20absolutely%20right%E2%80%94many%20new%20users%20run%20into%20similar%20issues%20with%20the%20examples%2C%20especially%20around%20the%20.env%20setup%20and%20directory%20permissions.%20The%20%22Permission%20denied%20%28os%20error%2013%29%22%20error%20usually%20means%20the%20process%20doesn%27t%20have%20write%20access%20to%20the%20directory%20specified%20by%20environment%20variables%20like%20OPENDAL_FS_ROOT%20or%20atomic_write_dir%2C%20or%20that%20the%20directory%20doesn%27t%20exist%20yet.%20This%20is%20a%20common%20stumbling%20block%20and%20has%20come%20up%20in%20several%20user%20reports%20and%20issues%20before%20%28%5Bexample%5D%28https%3A//github.com/apache/opendal/issues/5781%29%2C%20%5Bexample%5D%28https%3A//github.com/apache/opendal/i
ssues/5639%29%2C%20%5Bexample%5D%28https%3A//github.com/apache/opendal/issues/4867%29%29.%0A%0ATo%20make%20the%20README%20more%20newbie-friendly%2C%20it%20would%20help%20to%3A%0A%0A-%20Add%20step-by-step%20instructions%20for%20copying%20and%20editing%20the%20.env%20file%2C%20including%20which%20variables%20must%20be%20set%20for%20each%20example.%0A-%20Explicitly%20mention%20that%20directories%20like%20OPENDAL_FS_ROOT%20and%20atomic_write_dir%20must%20exist%20and%20be%20writable%20by%20the%20user%20running%20the%20example.%0A-%20Include%20a%20troubleshooting%20section%20for%20common%20errors%20like%20%22Permission%20denied%22%20or%20%22root%20is%20not%20specified%22%2C%20with%20tips%20on%20how%20to%20fix%20them%20%28e.g.%2C%20%60mkdir%20-p%20/path/to/dir%20%26%26%20chmod%20u%2Bw%20/path/to/dir%60%29.%0A-%20Clarify%20that%20some%20services%20%28like%20HDFS%29%20may%20require%20extra%20environment%20variables%20or%20system%20configuration.%0A%0AYour%20feedback%20matches%20what%20others
%20have%20experienced%2C%20and%20maintainers%20have%20discussed%20moving%20examples%20and%20improving%20docs%20to%20make%20onboarding%20smoother%20for%20everyone%20%28%5Bsee%20here%5D%28https%3A//github.com/apache/opendal/issues/2446%29%29.%20If%20you%20have%20specific%20suggestions%20or%20wording%20that%20helped%20you%2C%20sharing%20those%20would%20be%20valuable%20for%20making%20the%20docs%20even%20better%21) [](https://go.dosu.dev/discord-bot) [](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/apache/opendal/issues/6838)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@opendal.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Docs improve: make the README of core/examples easier for newbie [opendal]
Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo closed issue #6838: Docs improve: make the README of core/examples easier for newbie
URL: https://github.com/apache/opendal/issues/6838
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@opendal.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org