Skip to content

docs: tell tutorial readers what to do about the symlink error #2713

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tonyandrewmeyer wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: tell tutorial readers what to do about the symlink error #2713

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions ...-to-hero-write-your-first-kubernetes-charm/create-a-minimal-kubernetes-charm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,12 @@ The first time you run `charmcraft pack`, Charmcraft takes several minutes to pa

If you run into inexplicable issues when running `charmcraft pack`, this may be because some of the cached information is out of date. Run `charmcraft clean` to fix this.

```{tip}

**If packing fails with `OSError: [Errno 40] Too many levels of symbolic links`:** delete the `.tox` and `.venv` directories from your project and run `charmcraft pack` again. Tools like `tox` and `uv` create these virtual environments, and Charmcraft trips over the symbolic links inside them. Most of the reports so far are from people working in a VM on a Mac, and packing in destructive mode avoids the problem for some of them but not all. If you run into this, please add your environment details to [canonical/charmcraft#2661](https://github.com/canonical/charmcraft/issues/2661), which is where the bug is being tracked.

@dwilding dwilding Aug 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't mention destructive mode elsewhere, and people might get sidetracked by that - should they start troubleshooting? I think it's probably better to ask them to delete the dirs, add to the issue, then move on.

Suggested change
**If packing fails with `OSError: [Errno 40] Too many levels of symbolic links`:** delete the `.tox` and `.venv` directories from your project and run `charmcraft pack` again. Tools like `tox` and `uv` create these virtual environments, and Charmcraft trips over the symbolic links inside them. Most of the reports so far are from people working in a VM on a Mac, and packing in destructive mode avoids the problem for some of them but not all. If you run into this, please add your environment details to [canonical/charmcraft#2661](https://github.com/canonical/charmcraft/issues/2661), which is where the bug is being tracked.
**If packing fails with `OSError: [Errno 40] Too many levels of symbolic links`:** delete the `.tox` and `.venv` directories from your project and run `charmcraft pack` again. These virtual environments are created by tox and uv, and Charmcraft trips over the symbolic links inside them. If you see this error, please add your operating system details to [canonical/charmcraft#2661](https://github.com/canonical/charmcraft/issues/2661), which is where the bug is being tracked.

@gcomneno gcomneno Aug 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs suggestion makes sense to me — I agree that mentioning destructive mode there could send tutorial readers down an unnecessary troubleshooting path.

I had a look at canonical/charmcraft#2864 as well. As a Charmcraft-side mitigation, I think the approach is reasonable: ignoring top-level .venv and .tox prevents the problematic symlinks from reaching the local-source copy path in the first place, so it directly addresses the common reproducer without changing broader source-copy semantics.

I would still view it as a mitigation rather than the root fix, though. As you noted, nested virtual environments or an unrelated symlink that triggers the same llistxattr()/virtiofs behaviour could still fail in craft-parts. So I think merging something like #2864 could be useful in the short term, while separately investigating whether craft-parts should handle this filesystem behaviour more defensively.

The root-cause analysis in the PR looks plausible to me, and I would be interested in looking at the craft-parts side as well.


```

```{important}

**Did you know?** A `.charm` file is really just a zip file of your charm files and code dependencies that makes it more convenient to share, publish, and retrieve your charm contents.
Expand Down
6 changes: 6 additions & 0 deletions docs/tutorial/write-your-first-machine-charm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -556,6 +556,12 @@ Packed tinyproxy_amd64.charm

The name of the `.charm` file depends on your computer's architecture. For example, if your computer has an ARM-based architecture, the file is called `tinyproxy_arm64.charm`.

```{tip}

**If packing fails with `OSError: [Errno 40] Too many levels of symbolic links`:** delete the `.tox` and `.venv` directories from your project and run `charmcraft pack` again. Tools like `tox` and `uv` create these virtual environments, and Charmcraft trips over the symbolic links inside them. Most of the reports so far are from people working in a VM on a Mac, and packing in destructive mode avoids the problem for some of them but not all. If you run into this, please add your environment details to [canonical/charmcraft#2661](https://github.com/canonical/charmcraft/issues/2661), which is where the bug is being tracked.

```

### Deploy your charm

As you deploy your charm to Juju, it will be helpful to watch Juju status in real time.
Expand Down