← Back to issue list

Documentation links created by charmcraft are invalid

View original Github issue

Metadata

Project
charmcraft
Number
#2859
Type
issue
State
closed
Author
hk21702
Labels
—
Created
Updated
Closed

Current evaluation

Invalid help links were traced to incorrect Read the Docs configuration for Charmcraft 4.4; correcting the documentation setup restored valid versioned URLs without a Charmcraft code change.

Resolution: closed not a bug

Reason: The maintainer identified missing Read the Docs configuration as the root cause and stated that correcting it would resolve the 404s. The Charmcraft issue was closed after this documentation-side remediation rather than through a Charmcraft code fix.

Evaluated by: mr-cal-bot

No scores available.

Issue body

### Check existing issues - [x] I've verified that this bug isn't described by any existing issues. ### Bug description The documentation links provided by Charmcraft, such as when doing `charmcraft -h` or `charmcraft login -h`, point to an invalid page. The link is built with the full version of Charmcraft CLI, such as `4.4.1`, instead of `4` or `latest`, meaning the links point to nonexistent pages. ### Steps to reproduce 1. Run any command that would generate a documentation link, for example, `charmcraft -h` or `charmcraft login -h`. 2. Try to follow the link presented without modification 3. Observe 404! ### Environment charmcraft 4.4.1 ### charmcraft.yaml ```yaml If the issue is specific to a project, share its `charmcraft.yaml`. This field automatically renders as YAML, so you don't need to add special formatting. ``` ### Log output ```shell charmcraft login -h Usage: charmcraft login [options] Summary: Login to Charmhub. Charmcraft will prompt for your Ubuntu One email address and password. When you have successfully logged in, Charmcraft will store a token for ongoing access to Charmhub at the CLI (if `--export` option was not used otherwise it will only save the credentials in the indicated file). If `--export <file>` option is used, a secret credentials file will be created. And the file can be used to set `CHARMCRAFT_AUTH` environment variable. export CHARMCRAFT_AUTH=$(cat secret) This is suitable for Linux environments without a Vault, such as remote servers and CI/CD pipelines. Please ensure the secret file and environment variable are secured. Remember to `charmcraft logout` if you want to remove that token from your local system, especially in a shared environment. If the credentials are exported, they can also be attenuated in several ways specifying their time-to-live (`--ttl`), on which channels would work (`--channel`), what actions will be able to do (`--permission`), and on which packages they will work (using `--charm` or `--bundle`). See also `charmcraft whoami` to verify that you are logged in. Options: -h, --help: Show this help message and exit -v, --verbose: Show debug information and be more verbose -q, --quiet: Only show warnings and errors, not progress --verbosity: Set the verbosity level to 'quiet', 'brief', 'verbose', 'debug' or 'trace' -V, --version: Show the application version and exit --export: Export the Charmhub unencrypted secret credentials to a file --charm: The charm(s) on which the required credentials would work (this option can be indicated multiple times; defaults to all) --bundle: The bundle(s) on which the required credentials would work (this option can be indicated multiple times; defaults to all) --channel: The channel(s) on which the required credentials would work (this option can be indicated multiple times, defaults to any channel) --permission: The permission(s) that the required credentials will have (this option can be indicated multiple times, defaults to all permissions) --ttl: The time-to-live (in seconds) of the required credentials (defaults to 30 hours) See also: logout names register unregister whoami For a summary of all commands, run 'charmcraft help --all'. For more information, check out: https://documentation.ubuntu.com/charmcraft/4.4.1/reference/commands/login ```

Evaluation history

Date Model Scores Action Summary
stealth/space-bunny-alpha — closed not a bug Invalid help links were traced to incorrect Read the Docs configuration for Charmcraft 4.4; correcting the documentation setup restored valid versioned URLs without a Charmcraft code change.
stealth/space-bunny-alpha — closed not a bug Charmcraft’s 404 links were traced to incorrect Read the Docs configuration for the 4.4 documentation; correcting RTD setup was expected to restore valid /4/ URLs.
stealth/space-bunny-alpha
Impact: 35
Quick Win: 23
Complexity: 24
Confidence: 82
Actionability: 86
needs triage Charmcraft 4.4.1 generates 404 help links by embedding the full CLI version; the reproducer is clear, but this unlabelled issue has no maintainer triage.
qwen3.6-35b-a3b-mtp-q6
Impact: 60
Quick Win: 42
Staleness: 5
Complexity: 30
Confidence: 80
Support Request: 0
needs triage Charmcraft CLI help text generates invalid documentation links using full version numbers (e.g., 4.4.1) instead of stable or major version, causing 404 errors.
qwen/qwen3.8-27b
Impact: 30
Quick Win: 22
Staleness: 5
Complexity: 25
Confidence: 80
Support Request: 5
needs triage Charmcraft help output generates documentation URLs with the full CLI version (e.g. 4.4.1) instead of a valid docs path, causing 404s. Freshly reported, no labels or maintainer response yet; root cause is the {version} placeholder in docs_url in charmcraft/application/main.py.

Update history

Date Change
closed
updated
created

Related work

  • Related To: canonical/starbase#560 (confidence 90%)

    The maintainer explicitly described this documentation-versioning work as tangentially related.

Related issues

Issue Project State Summary Similarity
#2751 docs: previous doc versions all 404 charmcraft closed Missing migration redirects were fixed: Charmcraft 4.2 documentation URLs now redirect to their corresponding 4.3 pages.
77%
#1498 docs: Fix 404 in charmcraft.yaml.j2 charmcraft closed Merged in canonical/charmcraft#1498, correcting a broken charmcraft.yaml.j2 documentation link that returned 404.
76%
#2801 docs: add Charmcraft 4.4 release notes charmcraft merged Merged docs PR adding Charmcraft 4.4 release notes (commit 82e9de8b, 4 files, +188/-4), landing in docs/release-notes/charmcraft-4.4.rst and indexed in docs/release-notes/index.rst.
71%
#2376 docs: options for links in charmcraft unclear charmcraft open Docs gap: charmcraft.yaml reference doesn't list which sub-keys are allowed under `links:`; reporter's `upstream` key was rejected. Maintainer confirmed valid values live in the Links model; docs redo in progress.
71%
#2589 docs: add Charmcraft 4.2 release notes charmcraft merged Merged: release notes for Charmcraft 4.2 (dated 17 March 2026) added via commit ec9e0727 (+113 lines across docs/release-notes/charmcraft-4.2.rst and the release-notes index). CI failures were pre-existing/unrelated to the docs change.
70%