Convert validation errors to structured types with actionable suggestions

[Copilot]

Only 1% of validation errors included actionable suggestions despite having structured error infrastructure (ValidationError, ConfigurationError, OperationError) in place. Users received descriptions of problems without guidance on how to fix them.

Changes

Converted 43 validation errors across 10 files from plain fmt.Errorf to structured error types:

Before:

return fmt.Errorf("invalid mount at index %d: mode must be 'ro' or 'rw', got '%s'", i, mode)

After:

return NewValidationError(
    fmt.Sprintf("sandbox.mounts[%d].mode", i),
    mode,
    "mount mode must be 'ro' (read-only) or 'rw' (read-write)",
    "Change the mount mode to either 'ro' or 'rw'. Example:\nsandbox:\n  mounts:\n    - \"/host/path:/container/path:ro\"  # read-only\n    - \"/host/path:/container/path:rw\"  # read-write",
)

Files Converted

• sandbox_validation.go (9) - Mount syntax, feature flags, engine config, MCP gateway
• safe_outputs_domains_validation.go (13) - Domain patterns with visual examples (✓/✗)
• features_validation.go (2) - action-tag validation with git command examples
• expression_validation.go (2) - Expression safety with fuzzy match suggestions
• npm_validation.go (2) - Package validation with nvm/node install commands
• pip_validation.go (2) - Package validation with uv/pip setup instructions
• bundler_safety_validation.go (3) - Bundling errors with troubleshooting steps
• step_order_validation.go (3) - Compiler bug detection with issue tracker links
• runtime_validation.go (4) - Container images, packages, cache IDs, secrets
• mcp_gateway_schema_validation.go (3) - Schema compilation failures

Error Type Distribution

• ValidationError (30): User-facing validation with fix instructions
• ConfigurationError (5): Config problems with YAML examples
• OperationError (8): Compiler bugs with issue tracker links

Suggestion Coverage

• Before: 1/88 errors (1%) included suggestions
• After: 43/43 converted errors (100%) include actionable suggestions

All suggestions include installation commands, configuration examples, troubleshooting steps, or visual aids where helpful.

Remaining Work

68 errors in other validation files remain unconverted, including engine_validation.go, schema_validation.go, strict_mode_validation.go, and others.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Standardize validation errors to use structured error types</issue_title>
<issue_description>## Description

Convert validation errors across the codebase from plain fmt.Errorf to structured error types (ValidationError, ConfigurationError, OperationError). Currently, only 1% of validation errors include actionable suggestions despite having infrastructure in place.

Problem

Despite having well-designed error types with Suggestion fields, most validation errors use plain fmt.Errorf instead:

// Current pattern (no suggestions, no structure)
return fmt.Errorf("invalid mount at index %d: mode must be 'ro' or 'rw', got '%s'", i, mode)

// Should be (structured with suggestions)
return NewValidationError(
    fmt.Sprintf("sandbox.mounts[%d].mode", i),
    mode,
    "mount mode must be 'ro' (read-only) or 'rw' (read-write)",
    "Change the mount mode to either 'ro' or 'rw'. Example:\nsandbox:\n  mounts:\n    - \"/host/path:/container/path:ro\"",
)

Impact

• Severity: High
• Current State: Only 1 out of 88 ValidationError usages (1%) provide explicit suggestions
• User Impact: Users receive errors describing what's wrong but not how to fix it
• Files Affected: 83 validation files in pkg/workflow/

Files to Prioritize

1. pkg/workflow/sandbox_validation.go (many plain fmt.Errorf calls)
2. pkg/workflow/safe_outputs_domains_validation.go
3. All remaining *validation*.go files in pkg/workflow/

Suggested Changes

For each validation error using fmt.Errorf, convert to appropriate structured error type:

1. Field-level validation: Use NewValidationError(field, value, reason, suggestion)
2. Configuration errors: Use NewConfigurationError(configKey, value, reason, suggestion)
3. Operation failures: Use NewOperationError(operation, entityType, entityID, cause, suggestion)

Ensure every structured error includes:

• Clear reason explaining what's wrong
• Actionable suggestion for how to fix it (CRITICAL - currently only 1/88 errors have suggestions)
• Examples in the suggestion when helpful (especially for enum values, format requirements)

Success Criteria

• Identify all validation errors using plain fmt.Errorf in validation files
• Convert to appropriate structured error type
• Ensure all structured errors include actionable suggestions (target: >80% suggestion rate)
• Update error messages to include examples where helpful
• Maintain backward compatibility with existing error message content
• All tests pass after conversion
• Suggestion rate increases from 1% to >80%

Source

Extracted from Repository Quality Improvement: Validation Error Experience discussion githubnext/gh-aw#10683

Priority

High - Significantly improves user experience when debugging failed workflows

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 2, 2026, 2:08 PM UTC

Comments on the Issue (you are @copilot in this section)

• Fixes [Code Quality] Standardize validation errors to use structured error types #10686

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.