Skip to content

[task] Document top 20 error messages in troubleshooting guide #2974

@github-actions

Description

@github-actions

Objective

Extract and document the top 20 most common error messages from the codebase with solutions and examples.

Context

This addresses Issue #3 from discussion #2969. Out of 328 error messages in the codebase, zero are documented. This task focuses on documenting the most critical ones first.

Approach

  1. Search codebase for errors.New and fmt.Errorf patterns
  2. Identify the 20 most user-facing error messages based on:
    • Frequency of occurrence in code
    • Likelihood of user encountering them
    • Complexity requiring explanation
  3. For each error, document in docs/src/content/docs/troubleshooting/errors.md:
    • Error message text
    • What causes it
    • How to fix it
    • Working example (follow stop-time migration pattern)
  4. Include the exemplary errors mentioned in discussion [Schema Consistency] 🔍 Schema Consistency Check - Required Fields & Error Documentation Gap (Nov 2, 2025) #2969:
    • "cannot use 'command' with 'issues' in the same workflow"
    • "strict mode: 'network' configuration is required"
    • "job name cannot be empty"
    • "http MCP tool '%s' missing required 'url' field"

Files to Modify

  • docs/src/content/docs/troubleshooting/errors.md - Add top 20 error messages

Gold Standard Example

Follow the stop-time deprecation error pattern from compiler.go:

  • Clear explanation
  • Migration path
  • Working code example
  • Preserves user's value

Acceptance Criteria

AI generated by Plan Command for discussion #2969

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions