Documentation links created by charmcraft are invalid
Metadata
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. | |
| #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. | |
| #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. | |
| #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. | |
| #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. |