fix: improve error handling for OpenAI Compatible API providers #7487

roomote · 2025-08-28T09:01:49Z

Problem

Users encountering errors with OpenAI Compatible API providers (like qwen-coder and chatGLM4.5) were receiving vague "Roo encountered a problem" messages without actionable guidance for recovery.

Solution

Enhanced the error handling in BaseOpenAiCompatibleProvider to provide detailed, context-specific error messages with recovery suggestions.

Changes

Added enhanceErrorMessage method to analyze errors and provide helpful suggestions
Handle various error scenarios:
- 401 Authentication errors → Suggest verifying API key
- 404 Not found errors → Suggest checking base URL and model availability
- 429 Rate limiting → Suggest waiting and considering plan upgrades
- Connection errors → Provide network troubleshooting tips
- 500-503 Server errors → Suggest checking provider status
- Timeout errors → Suggest performance optimizations
Preserve original error properties for debugging
Added comprehensive test coverage for all error scenarios
Updated existing provider tests to match new error format

Testing

✅ Added new test suite for error handling scenarios
✅ All existing provider tests updated and passing
✅ Type checking passes
✅ Linting passes

Example Error Messages

Before

Roo encountered a problem

After

OpenAI Compatible API Error (Provider Name):
401 Unauthorized

Suggestions to resolve:
• Verify your API key is correct and active
• Check if the API key has proper permissions
• Ensure the API key is properly configured in settings

This provides users with clear, actionable steps to resolve their issues instead of leaving them confused about what went wrong.

Important

Enhances error handling for OpenAI Compatible API providers by adding detailed error messages and recovery suggestions in BaseOpenAiCompatibleProvider.

Behavior:
- Adds enhanceErrorMessage method in BaseOpenAiCompatibleProvider to provide detailed error messages and recovery suggestions.
- Handles errors like 401 (authentication), 404 (not found), 429 (rate limiting), connection errors, 500-503 (server errors), and timeouts.
- Preserves original error properties for debugging.
Testing:
- Adds new test suite base-openai-compatible-error-handling.spec.ts for error handling scenarios.
- Updates existing tests in chutes.spec.ts, featherless.spec.ts, fireworks.spec.ts, groq.spec.ts, io-intelligence.spec.ts, roo.spec.ts, sambanova.spec.ts, and zai.spec.ts to match new error format.
Misc:
- Fixes error message format in completePrompt method in base-openai-compatible-provider.ts.

^{This description was created by}^{for f577ee2. You can customize this summary. It will automatically update as commits are pushed.}

- Add detailed error messages with context-specific recovery suggestions - Handle various error types (401, 404, 429, connection, timeout, etc.) - Provide actionable guidance for users to resolve issues - Add comprehensive tests for error handling scenarios - Update existing provider tests to match new error format Fixes #7486

roomote

Reviewing my own code is like debugging in a mirror - everything looks backwards but the bugs are still mine.

roomote · 2025-08-28T09:06:52Z

src/api/providers/base-openai-compatible-provider.ts

+		let suggestions: string[] = []
+
+		// Check for common error patterns
+		if (error?.status === 401 || errorMessage.includes("401") || errorMessage.includes("Unauthorized")) {


The error detection logic here could be more robust. Currently, it relies on string matching (e.g., errorMessage.includes("401")) which could lead to false positives. For example, if an error message contains "401k retirement plan", it would incorrectly trigger authentication error suggestions.

Consider checking the status code first before falling back to string matching:

Suggested change

if (error?.status === 401 || errorMessage.includes("401") || errorMessage.includes("Unauthorized")) {

if (error?.status === 401 || (!error?.status && (errorMessage.includes("401") || errorMessage.includes("Unauthorized")))) {

roomote · 2025-08-28T09:06:53Z

src/api/providers/base-openai-compatible-provider.ts

+			suggestions.push("• You've hit the rate limit for this API")
+			suggestions.push("• Wait a moment before retrying")
+			suggestions.push("• Consider upgrading your API plan for higher limits")
+		} else if (error?.status === 500 || error?.status === 502 || error?.status === 503) {


Consider handling additional common error scenarios:

400 Bad Request (malformed request, invalid parameters)

403 Forbidden (different from 401 - has permission but action is forbidden)

422 Unprocessable Entity (common in OpenAI-compatible APIs for invalid model parameters)

These are frequently encountered and would benefit from specific guidance.

roomote · 2025-08-28T09:06:53Z

src/api/providers/base-openai-compatible-provider.ts

+			suggestions.push("• Try using a different model")
+		}
+
+		// Add general suggestions if no specific ones were added


Is this intentional? If an error matches multiple conditions (e.g., has status 401 AND message includes "Unauthorized"), the suggestions could be duplicated since we're using if-else. This actually prevents duplicates, but it means some errors might miss additional relevant suggestions. Consider collecting all applicable suggestions using a Set to allow multiple matches while avoiding duplicates.

roomote · 2025-08-28T09:06:53Z

src/api/providers/__tests__/base-openai-compatible-error-handling.spec.ts

+				expect(enhancedError.message).toContain("Check your provider's status page")
+			}
+		})
+	})


Consider adding test cases for edge scenarios:

Errors with both status codes and matching message strings (to verify no duplicate suggestions)

Null/undefined error objects

Errors with circular references in properties

These edge cases could help ensure the error handler is robust against unexpected inputs.

roomote · 2025-08-28T09:06:53Z

src/api/providers/base-openai-compatible-provider.ts

 		}
 	}

+	/**


The method could benefit from JSDoc documentation with examples:

Suggested change

/**

/**

* Enhances error messages with helpful guidance for OpenAI Compatible API issues

* @example

* // Input: Error { message: "401 Unauthorized", status: 401 }

* // Output: Error { message: "OpenAI Compatible API Error...\n\nSuggestions..." }

*/

daniel-lxs · 2025-08-29T04:45:03Z

Closing, see #7486 (comment)

roomote bot requested review from cte, jr and mrubens as code owners August 28, 2025 09:01

github-project-automation bot added this to Roo Code Roadmap and Roo Code Roadmap Aug 28, 2025

github-project-automation bot moved this to Triage in Roo Code Roadmap Aug 28, 2025

github-project-automation bot moved this to New in Roo Code Roadmap Aug 28, 2025

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. bug Something isn't working labels Aug 28, 2025

roomote bot commented Aug 28, 2025

View reviewed changes

roomote bot mentioned this pull request Aug 28, 2025

Roo encountered a problem... This may indicate a failure in the model thinking process or an inability to use the tool correctly, which can be alleviated through user guidance (e.g.,"Try to break down the task into smaller steps"). #7486

Closed

hannesrudolph added the Issue/PR - Triage New issue. Needs quick review to confirm validity and assign labels. label Aug 28, 2025

CCranney mentioned this pull request Aug 28, 2025

Error 404 in Roo-Code, but Replicable using openai in python #7498

Closed

daniel-lxs closed this Aug 29, 2025

github-project-automation bot moved this from Triage to Done in Roo Code Roadmap Aug 29, 2025

github-project-automation bot moved this from New to Done in Roo Code Roadmap Aug 29, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: improve error handling for OpenAI Compatible API providers #7487

fix: improve error handling for OpenAI Compatible API providers #7487

Uh oh!

roomote bot commented Aug 28, 2025 •

edited by ellipsis-dev bot

Loading

Uh oh!

roomote bot left a comment

Uh oh!

roomote bot Aug 28, 2025

Uh oh!

roomote bot Aug 28, 2025

Uh oh!

roomote bot Aug 28, 2025

Uh oh!

roomote bot Aug 28, 2025

Uh oh!

roomote bot Aug 28, 2025

Uh oh!

daniel-lxs commented Aug 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	if (error?.status === 401 \|\| errorMessage.includes("401") \|\| errorMessage.includes("Unauthorized")) {
	if (error?.status === 401 \|\| (!error?.status && (errorMessage.includes("401") \|\| errorMessage.includes("Unauthorized")))) {

               		}
               	}
+              	/**

-	/**
+/**
+ * Enhances error messages with helpful guidance for OpenAI Compatible API issues
+ * @example
+ * // Input: Error { message: "401 Unauthorized", status: 401 }
+ * // Output: Error { message: "OpenAI Compatible API Error...\n\nSuggestions..." }
+ */

fix: improve error handling for OpenAI Compatible API providers #7487

fix: improve error handling for OpenAI Compatible API providers #7487

Uh oh!

Conversation

roomote bot commented Aug 28, 2025 • edited by ellipsis-dev bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Changes

Testing

Example Error Messages

Before

After

Uh oh!

roomote bot left a comment

Choose a reason for hiding this comment

Uh oh!

roomote bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

roomote bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

roomote bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

roomote bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

roomote bot Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

daniel-lxs commented Aug 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

roomote bot commented Aug 28, 2025 •

edited by ellipsis-dev bot

Loading