Skip to content

fix(docs): errors page omits exit code 10 and gives a conflicting meaning for 7 #1028

Closed

Description

@coygeek

Summary

The errors page's headless exit-code table omits insufficient credits and describes the API server error code as an internal error. Readers get different guidance depending on which documentation page they consult.

Steps to reproduce

  1. Open the errors page and inspect its "Headless exit codes" table.
  2. Compare it with the headless page, under "Exit codes".
  3. Optionally inspect the published package's dist/cli.mjs exit-code constants and dist/bundled/command-code-knowledge/reference/headless.md exit-code table for the release identified below.

Both page fetches and the package inspection were executed. Reproducing a live insufficient-credit response is unnecessary for this documentation comparison and was not attempted.

Expected behavior

The errors page should document the same supported headless exit codes and meanings as the headless reference and published package. In particular, code 10 should identify insufficient credits, and code 7 should identify an API server error.

Actual behavior

Both pages returned HTTP 200. The errors table contains codes 0, 1, 3, 4, 5, 6, 7, 8, 9, and 130, with no row for 10. Its row for 7 says "Internal error". The headless table includes 10 as "Insufficient credits" and describes 7 as "API server error (5xx)".

The package's bundled reference agrees with the headless page. Its CLI bundle defines SERVER_ERROR:7 and INSUFFICIENT_CREDITS:10; classifyPrintModeError maps an insufficient-credits error message to the latter constant and an API server error to the former.

Runtime or environment

  • Command Code Version: 1.82.4, the npm latest release at verification, freshly installed into an isolated prefix and confirmed with cmd --version --no-auto-update.
  • Operating System: macOS.
  • Terminal/IDE: command-line inspection; no interactive or model session was used.
  • Shell: bash-compatible reproduction steps; the issue concerns hosted documentation.
  • The tracker default branch main was inspected at c48f96f. It contains the issue intake and no hosted documentation source, so the published pages are the documentation baseline.

Evidence

  • Expected source: The headless page's "Exit codes" table, corroborated by the published package's bundled reference/headless.md table and dist/cli.mjs constants and error classifier.
  • Failure source: The errors page's "Headless exit codes" table, fetched directly with curl -sSL -A 'Mozilla/5.0' and compared with the headless table.
  • Evidence provenance: observed
  • Local verification: reproduced
  • Reproduction completeness: complete

Both hosted tables were fetched and inspected locally. The package constants and classifier were also inspected statically. No live credit exhaustion or API server failure was induced.

Relevant rows from the fetched tables:

Code Errors page Headless page
7 Internal error API server error (5xx)
10 No row Insufficient credits

Restoration check

Fetch both pages again and compare their exit-code tables with the published package's constants and bundled reference. The errors table should include insufficient credits at 10 and identify API server errors at 7. Check the other currently listed codes as a control so correcting these rows does not remove existing guidance. No credit-consuming run is required to verify this documentation correction.

Triage assessment

  • Impact level: P3
  • Assessment status: supported
  • Impact basis: The observed defect is incomplete and inconsistent documentation. No runtime behavior change or downstream automation failure was observed.
  • Workaround status: available
  • Workaround basis: The published headless page and bundled headless reference already list code 10 and identify code 7 as an API server error; readers can use those verified tables.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions