AltimateAI / AltimateAI/altimate-code

[Feature] User-friendly error handling with error codes and suggestions

Abierto
#60 0 comentarios 0 reacciones 0 asignados Ver en GitHub
enhancement error-handling priority:high ux
Lenguaje dominante
TypeScript
Estrellas
811
Forks
134
Merge medio
3 d 2 h
PR fusionados (30 d)
50

Descripción

## Problem

Several error paths expose raw stack traces, internal file paths, and generic messages to users. This makes the tool look unpolished and leaves users unable to self-diagnose issues.

**Examples found during testing:**

1. **Invalid model:** `altimate run --model nonexistent/model "hello"` shows:
```
ProviderModelNotFoundError: ProviderModelNotFoundError
data: { providerID: "nonexistent", modelID: "model", suggestions: [] }
at getModel (src/provider/provider.ts:1157:13)
```

2. **Bridge timeout:** Shows `Bridge timeout: sql.execute (30000ms)` with no guidance on cause or fix

3. **Bridge crash:** Shows `Python bridge failed after max restarts` — cryptic, no recovery steps

4. **Warehouse failure:** Shows `Failed to connect to warehouse 'x'. Error: Unknown error` — no distinction between auth, network, or permission errors

5. **Generic fallback:** `FormatUnknownError` in `src/cli/error.ts` returns `error.stack` for any unrecognized error

## Proposed Solution

### 1. Error taxonomy with codes

Create an error classification system:

```
ALT-1xxx: Configuration errors (missing config, invalid JSON, bad model name)
ALT-2xxx: Authentication errors (invalid API key, expired token, missing credentials)
ALT-3xxx: Bridge errors (timeout, crash, restart failure, missing Python)
ALT-4xxx: Warehouse errors (connection refused, auth failed, driver missing, query timeout)
ALT-5xxx: SQL errors (parse failure, validation error, dialect mismatch)
ALT-6xxx: Tool errors (skill not found, MCP server failure)
```

### 2. Error message format

Replace stack traces with structured user-friendly messages:

```
✗ Could not connect to warehouse 'prod_snowflake' (ALT-4001)

Cause: Authentication failed — invalid password or expired credentials

Try:
• Verify your password in altimate-code.json or env var SNOWFLAKE_PASSWORD
• Test connection outside altimate: snowsql -a -u
• Check account name format: should be "xy12345.us-east-1"

Debug: altimate --print-logs --log-level DEBUG
Docs: https://altimate-code.sh/troubleshooting#ALT-4001
```

### 3. "Did you mean?" suggestions

Already partially implemented for models via fuzzysort. Extend to:
- Provider names
- Agent names
- Warehouse connection names
- Slash commands

### Key files to modify
- `packages/altimate-code/src/cli/error.ts` — `FormatUnknownError` function (remove `error.stack` from user output)
- `packages/altimate-code/src/bridge/client.ts` — Bridge timeout/crash error messages (lines ~54, 90, 140, 156)
- `packages/altimate-code/src/provider/provider.ts` — `ProviderModelNotFoundError` and provider init errors
- `packages/altimate-code/src/tool/warehouse-test.ts` — Warehouse connection error messages
- `packages/altimate-code/src/tool/sql-execute.ts` — SQL execution error messages
- All tool files in `packages/altimate-code/src/tool/` — Standardize error output format

### Industry patterns
- **Aider:** Never shows stack traces. Typo → suggests alternatives. Missing credential → lists exact env vars
- **Goose:** Categorizes errors (auth=401, rate-limit=429, server=500) with per-category retry behavior
- **Rust/Cargo:** Error codes with `--explain E0308` for detailed docs
- **Fuchsia CLI guidelines:** Unique error identifier (e.g., `fi-0123`) for searchable error catalog

### Acceptance criteria
- [ ] No stack traces in default user-facing output
- [ ] Stack traces logged to `~/.local/share/altimate-code/log/` and shown with `--print-logs --log-level DEBUG`
- [ ] Error codes follow `ALT-XXXX` format
- [ ] Bridge errors classified: timeout vs crash vs missing dependency vs auth
- [ ] Warehouse errors classified: connection refused vs auth failed vs driver missing
- [ ] Invalid model/provider names suggest alternatives via fuzzy matching
- [ ] Error messages include actionable "Try:" suggestions

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.