Preview command doesn't work on Linux

[RandomHashTags]

I tried this command: swift package --disable-sandbox preview-documentation --target APIDocumentation

And got this output:

Build of target: 'APIDocumentation' complete! (4.04s)
Template: /usr/lib/swift/share/docc/render
Error: Error Domain=NSCocoaErrorDomain Code=513 "You don’t have permission."
error: 'docc preview' invocation failed with a nonzero exit code: '1'.

Note: The Swift-DocC Preview plugin requires passing the '--disable-sandbox' flag
to the Swift Package Manager because it requires local network access to
run a local web server. See 'swift package plugin preview-documentation --help' for details.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

Start web server to preview docc documentation.

Actual behavior

It says I don't have permission.

Steps to Reproduce

OS: Arch Linux 6.12.1-arch1-1
IDE: VS Code (1.95.2)

Project is a Swift Package with 1 module named "APIDocumentation" with two files:

• Test.md with a single line of # Test
• APIDocumentation.swift with 3 lines:

/// Test dude
struct APIDocumentation {
}

Execute the command listed above, which is described on the README to preview docc documentation.

Swift-DocC Plugin Version Information

Swift-DocC plugin version:
1.4.3

Swift Compiler version:
Swift version 6.0.2 (swift-6.0.2-RELEASE)
Target: x86_64-unknown-linux-gnu

[tayloraswift]

this is also happening to me in an Ubuntu 24.04 devcontainer

[RandomHashTags]

I think this issue should be transferred to swiftlang/swift-docc as the docc subcommands are the source of the problem, not this repo.

Edit: All unit tests pass on my Linux machine for swiftlang/swift-docc. The problem is this repo.

[jessezamora]

I had this issue and set out to figure out why, since it was affecting my ability to build documentation from my CI. And I found that having Swift installed at /usr with the default root permissions actually causes docc and the swift-docc-plugin to give the permission error:

Error: Error Domain=NSCocoaErrorDomain Code=513 "You don’t have permission."
error: 'docc convert' invocation failed with a nonzero exit code: '1'
error: Error Domain=NSCocoaErrorDomain Code=4 "The file doesn’t exist."

But, upon moving the Swift installation to the home directory and updating the PATH to ~/swift-6.0.3-RELEASE-ubuntu22.04/usr/bin to test, it works perfectly:

Generated documentation archive at:
  /home/usjz/tmp/swift-async-algorithms/.build/plugins/Swift-DocC/outputs/AsyncAlgorithms.doccarchive

So @tayloraswift do you think this is worth filing a bug for? It seems like an issue with swift-docc itself, when Swift is installed to a path with root permissions.

[xtremekforever]

I filed a bug against swift-docc here: swiftlang/swift-docc#1136