Skip to content

Generated auth error hints hardcode a Bearer-token mental model (and a placeholder "get a key" URL), steering users toward a scheme the API rejectsΒ #2465

Closed

Description

@joshuatownsend

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 doctor command (auth_hint, auth_key_url fields and printed output),
  • the auth command's onboarding/help text and browser-launch URL,
  • the generated MCP tool error handling (same strings, surfaced to the agent).

Reproduction

  1. Generate a CLI from a spec whose securitySchemes is HTTP Basic (not Bearer).
  2. Make any authenticated request without (or with malformed) credentials.
  3. 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)

  1. Derive the hint from the spec's security scheme. The generator already knows
    the scheme from components.securitySchemes:
    • http/basic β†’ tell users to provide a Basic credential / run the generated
      login command, not to set a Bearer token var.
    • http/bearer or oauth2 β†’ 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.
  2. 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/HATEOAS to users.
  3. 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).
  4. 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

Activity

  1. added
    bugSomething isn't working
    priority:P2Medium priority: meaningful recurring defect or capability gap
    on May 31, 2026
  2. self-assigned this
    on Jun 8, 2026
  3. tmchow commented on Jun 8, 2026

    @tmchow
    Owner

    I’m picking this up and will keep the fix scoped to the generated auth hint surfaces.

  4. joshuatownsend commented on Jul 7, 2026

    @joshuatownsend
    ContributorAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingcomp:generatorpriority:P2Medium priority: meaningful recurring defect or capability gap

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions