fix: improve error message formatting for prompt errors

[jbshu4546]

Issue #, if available: 2043

Description of changes:

Clean up the error message shown to Q CLI users when @<prompt> is invoked with missing/malformed inputs. See comments for more details.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[jbshu4546]

Idea Honing - Requirements Clarification

This document will contain questions and answers to refine the initial idea and develop a thorough specification.

Question 1

What specific issues are there with the current error messages when @<prompt> is invoked with missing/malformed inputs?

Answer 1

The current error messages are hard to decipher. They display technical JSON error structures that aren't user-friendly. Example of current error:

Error encountered while retrieving prompt:
{
  "code": -32602,
  "message": "MCP error -32602: Invalid arguments for prompt agent_script_coco_was_sev2_ticket_details_retrieve: [\n  {\n    \"code\": \"invalid_type\",\n    \"expected\": \"object\",\n    \"received\": \"undefined\",\n    \"path\": [],\n    \"message\": \"Required\"\n  }\n]"
}

The issues include:

• Technical JSON error format that's not user-friendly
• Raw error codes (-32602) without explanation
• Nested error structures with escape characters (\n)
• No clear guidance on how to fix the issue
• Missing information about what parameters are required

Question 2

What would you like the improved error messages to look like? Do you have a specific format or style in mind?

Answer 2

The improved error messages should have:

1. At minimum:

   • Unescaped characters (no \n escape sequences)
   • Properly formatted nested JSON structure with appropriate line breaks
   • Better visual formatting of the error content

2. Ideally (if Q CLI has control over the error message content):

   • Natural language explanations of each error
   • Example: "Parameter code is undefined, expected object"
   • Clear indication of which parameters are missing or malformed
   • Guidance on how to correctly format the command

Question 3

Do you know which part of the codebase handles these error messages? If so, can you provide information about the relevant files or modules?

Answer 3

The error message is coming from line 2552 of crates/cli/src/cli/chat/mod.rs in the Amazon Q CLI codebase.

Question 4

Are there any specific constraints or requirements we need to consider when implementing this improvement? For example, compatibility with different terminal types, color support, or maintaining backward compatibility?

Answer 4

The implementation should:

• Maintain the existing red color for error messages
• Follow the existing code style of the codebase
• Adhere to the project's commit message format
• Ensure changes align with the overall design patterns used in the codebase

Question 5

Would you like to examine the current implementation in the codebase to better understand how the error messages are currently generated and displayed?

[jbshu4546]

Detailed Design: Improved Error Messages for Q CLI

Overview

This design document outlines the approach for improving error messages displayed to users when @<prompt> is invoked with missing/malformed inputs in the Amazon Q CLI. The goal is to make these error messages more user-friendly by properly formatting JSON structures, unescaping escape sequences, and presenting the information in a clear, readable manner.

Requirements

Based on the requirements clarification, the improved error messages should:

1. Minimum Requirements:

   • Unescape characters (no \n escape sequences)
   • Properly format nested JSON structure with appropriate line breaks
   • Better visual formatting of the error content

2. Ideal Requirements (if possible):

   • Natural language explanations of each error
   • Clear indication of which parameters are missing or malformed
   • Guidance on how to correctly format the command

3. Constraints:

   • Maintain the existing red color for error messages
   • Follow the existing code style of the codebase
   • Adhere to the project's commit message format
   • Ensure changes align with the overall design patterns used in the codebase

Architecture

The solution will focus on modifying the error message display in crates/cli/src/cli/chat/mod.rs around line 2552. The current implementation simply pretty-prints the JSON error message, but doesn't handle escape sequences properly.

Components and Interfaces

1. Error Message Formatter

   • A new function to format MCP error messages in a user-friendly way
   • Will parse and extract relevant information from the error message
   • Will handle unescaping of escape sequences

2. Integration with Existing Code

   • Modify the existing error display code to use the new formatter
   • Maintain the existing styling (bold header, red text)

Data Models

MCP Error Structure

Based on the example error message, MCP errors have the following structure:

{
  "code": -32602,
  "message": "MCP error -32602: Invalid arguments for prompt agent_script_coco_was_sev2_ticket_details_retrieve: [
    {
      "code": "invalid_type",
      "expected": "object",
      "received": "undefined",
      "path": [],
      "message": "Required"
    }
  ]"
}

The key components are:

• code: An error code (e.g., -32602)
• message: A string containing:
  • Error code prefix
  • Description
  • Nested JSON array with validation errors

Formatted Error Structure

The formatted error will maintain the same information but present it in a more readable way:

Error encountered while retrieving prompt:

MCP error -32602: Invalid arguments for prompt agent_script_coco_was_sev2_ticket_details_retrieve:
[
  {
    "code": "invalid_type",
    "expected": "object",
    "received": "undefined",
    "path": [],
    "message": "Required"
  }
]

Implementation Details

New Error Formatter Function

We'll create a new function format_mcp_error that will:

1. Parse the error JSON
2. Extract the message field
3. Identify if there's a nested JSON array in the message
4. Parse and pretty-print the nested JSON
5. Return a formatted error message with proper newlines and indentation

fn format_mcp_error(err: &serde_json::Value) -> String {
    // Extract the message field
    if let Some(message) = err.get("message").and_then(|m| m.as_str()) {
        // Check if the message contains a JSON array
        if let Some(start_idx) = message.find('[') {
            if let Some(end_idx) = message.rfind(']') {
                let prefix = &message[..start_idx].trim();
                let nested_json = &message[start_idx..=end_idx];
                
                // Try to parse the nested JSON
                if let Ok(nested_value) = serde_json::from_str::<serde_json::Value>(nested_json) {
                    // Format the error message
                    return format!(
                        "{}\n{}",
                        prefix,
                        serde_json::to_string_pretty(&nested_value)
                            .unwrap_or_else(|_| nested_json.to_string())
                    );
                }
            }
        }
        // If we couldn't extract and parse nested JSON, return the original message
        return message.to_string();
    }
    
    // Fallback to pretty-printing the entire error
    serde_json::to_string_pretty(err).unwrap_or_else(|_| format!("{:?}", err))
}

Integration with Existing Code

We'll modify the existing error display code to use our new formatter:

if let Some(err) = prompts.error {
    // If we are running into error we should just display the error
    // and abort.
    let to_display = serde_json::json!(err);
    queue!(
        self.output,
        style::Print("\n"),
        style::SetAttribute(Attribute::Bold),
        style::Print("Error encountered while retrieving prompt:"),
        style::SetAttribute(Attribute::Reset),
        style::Print("\n"),
        style::SetForegroundColor(Color::Red),
        style::Print(format_mcp_error(&to_display)),
        style::SetForegroundColor(Color::Reset),
        style::Print("\n"),
    )?;
    // ...
}

Error Handling

The error formatter will include fallback mechanisms to ensure that even if parsing fails, the user will still see an error message:

1. If parsing the nested JSON fails, fall back to the original message
2. If extracting the message field fails, fall back to pretty-printing the entire error
3. If pretty-printing fails, fall back to the debug format

Testing Strategy

The implementation should be tested with various error message formats:

1. Standard MCP errors with nested JSON
2. MCP errors without nested JSON
3. Non-MCP errors
4. Edge cases (empty messages, malformed JSON, etc.)

Unit tests should verify that:

1. The formatter correctly extracts and formats nested JSON
2. The formatter handles edge cases gracefully
3. The output is properly formatted with newlines and indentation

Implementation Considerations

1. Performance Impact: The additional parsing and formatting should have minimal performance impact since error messages are displayed infrequently.

2. Error Handling: The implementation should be robust and handle unexpected error formats gracefully.

3. Maintainability: The code should be well-documented to explain the parsing and formatting logic.

4. Future Extensibility: The formatter should be designed to accommodate potential changes in error message formats.

[jbshu4546]

Result when arguments object is omitted:

@{prompt_name}

Error encountered while retrieving prompt:
MCP error -32602: Invalid arguments for prompt {prompt_name}:
[
  {
    "code": "invalid_type",
    "expected": "object",
    "message": "Required",
    "path": [],
    "received": "undefined"
  }
]

Result when arguments object is malformed:

@{prompt_name} ""

Error encountered while retrieving prompt:
MCP error -32602: Invalid arguments for prompt {prompt_name}:
[
  {
    "code": "invalid_type",
    "expected": "string",
    "message": "Required",
    "path": [
      "{inputVariable1}"
    ],
    "received": "undefined"
  },
  {
    "code": "invalid_type",
    "expected": "string",
    "message": "Required",
    "path": [
      "{inputVariable2}"
    ],
    "received": "undefined"
  }
]

[brandonskiser]

Hey, sorry for such a late reply - this PR is out of date with the current implementation so I'm going to close it. Please raise if there's some other update you'd like to make here, thank you!