AltimateAI / AltimateAI/altimate-code
[Feature] User-friendly error handling with error codes and suggestions
- Vorherrschende Sprache
- TypeScript
- Sterne
- 811
- Forks
- 134
- Ø Merge
- 3 T. 2 Std.
- Gemergte PRs (30 T.)
- 50
Beschreibung
## 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
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.