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

[tonyandrewmeyer]

Packing a charm that has a .tox or .venv directory can fail with OSError: [Errno 40] Too many levels of symbolic links, which is confusing to hit part-way through a tutorial. This adds a tip after the charmcraft pack step in both the Kubernetes and the machine tutorial, giving the workaround (delete those directories and pack again) and pointing at canonical/charmcraft#2661, where the bug is tracked, so that people can add their environment details.

This covers both tutorials, and describes the symptoms the way the charmcraft issue does rather than blaming non-destructive mode: destructive mode helps some people and not others, and most of the reports are from a VM on a Mac.

This is a stop-gap, so it should come out again when charmcraft#2661 is fixed. @dwilding wanted to hear from the Charmcraft team before we documented their bug and I don't think we ever did, so if you'd rather wait, that's fine by me - but the issue hasn't moved since April.

Preview

Fixes #2441

[tonyandrewmeyer]

@dwilding what do you think about this one, now that more time has passed? I'm still preferring that it's fixed upstream rather than documented here, but asking people who hit it to help by recording their issues on the charmcraft issue could help.

I'm definitely open to just rejecting the issue instead. But if you'd still like a note, what about this as one?

[gcomneno]

Thanks for picking this up and expanding it to both tutorials.

This matches what I observed when I worked on #2452, and I think linking directly to canonical/charmcraft#2661 makes the workaround more useful without presenting it as the root fix.

The revised wording also looks better to me because it describes the actual symptom without tying it too strongly to destructive vs non-destructive mode.

[dwilding]

Thanks for raising this again. As there's been no movement on the issue, I'm good with updating the docs. But I think we (I) should try to get a fix moving. I've opened canonical/charmcraft#2864 as a first attempt. Do you have any opinion about it?

[dwilding]

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]

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.