Repository navigation
Description
Project: CLI Printing Press
Component: generated auth error hints β doctor, client/CLI error helpers, and MCP tool error handling
Type: codegen correctness / UX
Summary
When an authenticated request fails (400-with-auth-signal / 401 / 403), the
generated code prints a remediation hint. Those hints are hardcoded to a single
Bearer-token mental model regardless of the API's actual security scheme:
hint: ... is missing or invalid.
Set your API key: export <PREFIX>_TOKEN=<your-key>
Get a key at: https://en.wikipedia.org/wiki/HATEOAS
Run '<cli> doctor' to check auth status.
Two distinct defects:
1. The hint assumes a Bearer token even when the spec's security scheme is HTTP Basic (or anything non-Bearer)
The generated credential plumbing turns <PREFIX>_TOKEN into an
Authorization: Bearer <token> header. For an API whose declared security scheme
is HTTP Basic (or a custom/session scheme), that header is rejected β so the
hint tells the user to do the one thing that cannot work, and never mentions the
mechanism that does (e.g. the generated login command, or an <PREFIX>_AUTH_HEADER
verbatim-header path).
This is not hypothetical: it actively misled an operator and an LLM agent
debugging a real failure. The API rejected the wrong scheme with
HTTP 403 {"code":"InvalidAuthorizationScheme"}; the agent read the generated
export <PREFIX>_TOKEN hint, concluded the tool wanted a Bearer token, and spent
the session chasing a Bearer credential β when the API only accepts Basic. The
hint pointed directly away from the fix.
2. The "Get a key at:" URL is an un-substituted template placeholder
The URL shipped in the hint text (and in doctor's JSON envelope as
auth_key_url, and as the browser-launch target of the login command) is literally:
https://en.wikipedia.org/wiki/HATEOAS
That is obviously a templating default that was never substituted with the API's
real credential/token documentation URL. A Wikipedia article on HATEOAS is now the
official "where do I get a key" answer the CLI gives every user.
3. (Secondary) The 403 hint presumes a permissions problem
The 403 branch prints "your credentials are valid but lack access to this
resource." But a 403 can also mean the auth scheme/format is unsupported (as
above), where the fix is to correct the credential, not request more access. The
hardcoded text misdiagnoses that case.
Where it appears (all generated)
The same hardcoded <PREFIX>_TOKEN + placeholder-URL hint is emitted from multiple
generated surfaces, so a user hits it no matter which entry point they use:
- the CLI error helper (401/403 handling around live requests),
- the
doctorcommand (auth_hint,auth_key_urlfields and printed output), - the
authcommand's onboarding/help text and browser-launch URL, - the generated MCP tool error handling (same strings, surfaced to the agent).
Reproduction
- Generate a CLI from a spec whose
securitySchemesis HTTP Basic (not Bearer). - Make any authenticated request without (or with malformed) credentials.
- Observe the hint instructs
export <PREFIX>_TOKEN=β¦(β a Bearer header the API
rejects) and "Get a key at: https://en.wikipedia.org/wiki/HATEOAS".
Suggested fixes (any subset)
- Derive the hint from the spec's security scheme. The generator already knows
the scheme fromcomponents.securitySchemes:http/basicβ tell users to provide a Basic credential / run the generated
login command, not to set a Bearer token var.http/beareroroauth2β the token var is correct.- reference the generated login command (and
doctor) the tool actually
ships, instead of (or in addition to) a raw env var.
- Stop shipping the placeholder URL. Source "get a key at" from the spec
(an OAuth flow's*Url/documentation URL,externalDocs,info.contact, or a
vendor extension), or omit it entirely when unknown. Never emit
https://en.wikipedia.org/wiki/HATEOASto users. - Make the 403 hint scheme-aware (or just echo the server's error
code/body).
Distinguish "unsupported auth scheme / malformed credential" (fix the credential)
from genuine "authenticated but forbidden" (request access). - Surface the server's structured error (
code+message) in the hint rather
than a generic guess β it's usually more accurate than any templated remediation.
Notes
- All affected files carry the generated
DO NOT EDITheader, so this can't be
fixed downstream without diverging from regeneration β it needs a generator fix. - Related generated-code issues filed/drafted for this same project: store
typed-tableparent_id(Generated typed-table sync drops all rows: parent-FK column is NOT NULL but never populatedΒ #2457),jobs.goGetNoCachearity (v4.19.0: generated jobs.go calls c.GetNoCache(path, nil) β missing ctx arg, fails to compileΒ #2458),sync
auto-mirroring computed dependents, andsearchfeeding raw input into FTS5
MATCHunquoted.
Activity
tmchow commentedon Jun 8, 2026
Iβm picking this up and will keep the fix scoped to the generated auth hint surfaces.
joshuatownsend commentedon Jul 7, 2026
Still reproduces in v4.27.1: the generated auth error hints still hardcode a Bearer / _TOKEN model regardless of the spec's declared security scheme (e.g. an API whose scheme is HTTP Basic), steering users toward a scheme the API rejects.