Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat(*): extend provider error guidance to channels, tui, and transcription

Open
  • Is something wrong?
#336 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
58/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python
Domain
backend, cli

Research direction

Start by reading parse_llm_error and format_llm_error in raven/providers/base.py, then trace the consumers in raven/cli/agent_commands.py, raven/cli/tui_commands.py, raven/tui_rpc/methods/config.py, and raven/providers/transcription.py. Done means channels and the TUI show category-specific guidance with surface-appropriate hints, while missing Groq transcription credentials produce a one-line configuration hint instead of an unexplained empty transcript.

Written by the indexing model from the issue text.

Description

Problem

Provider errors are normalized into a canonical single-line form (built by format_llm_error, machine-parseable via parse_llm_error in raven/providers/base.py:116 and :145), and the CLI one-shot path renders them as a friendly diagnosis plus a Fix hint with a nonzero exit. Other surfaces did not get the same treatment:

  1. Channels and the TUI deliver the raw canonical line, e.g. Error calling LLM (auth@openrouter): AuthenticationError: ... User not found. This is better than the old raw exception dump, but has no category-appropriate hint and no Fix line.
  2. Missing-credential remedies travel to the TUI as a raw remedy string that tells the user to run terminal commands, which is awkward inside the TUI.
  3. Groq transcription with no API key only logs "Groq API key not configured for transcription" and silently returns an empty transcript, so the user just sees the agent ignore their voice message with no hint about where to configure the key.

Evidence

  • parse_llm_error is consumed only by raven/cli/agent_commands.py:76; no channel or TUI rendering path uses it.
  • raven/cli/tui_commands.py:528 and raven/tui_rpc/methods/config.py:345 forward the remedy text verbatim into RPC error data.
  • raven/providers/transcription.py:31 warns and returns "" with no fix guidance.
  • Auth error rendering deliberately avoids naming a specific HTTP status (401 vs 403 cannot be distinguished from the exception across providers), so the line currently says the provider rejected the credentials without a status.

Suggested direction

  • Reuse parse_llm_error in the channel outlet and TUI rendering so every surface gets the same category-based diagnosis plus a surface-appropriate hint (channels can point at gateway/provider config; the TUI can point at its own config screen instead of terminal commands).
  • Give the transcription no-key warning the same one-line fix hint the chat path has.
  • If showing the real HTTP status is ever wanted: a sketched design exists where format_llm_error extracts the status from the live exception into the canonical header ((<category>[@<provider>][ <status>])), parse_llm_error returns it as an extra field, and the render layer chooses between the real value and a neutral word. That keeps the status truthful end to end instead of hardcoding one in the renderer.
Dominant language
Python
Stars
4.1k
Forks
94
Avg merge
10h 2m
Merged PRs (30d)
376

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EverMind-AI/Raven

All issues in EverMind-AI/Raven

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.