Skip to content
Sign in

Stack Traces

Live Trace Analysis

Votrio intercepts stack traces in real-time as your process runs and explains the root cause with AI analysis — all directly in your terminal.

How It Works

When you run votrio run "your-command", votrio:

  1. Spawns your process and captures all stderr output
  2. Watches for stack trace patterns (Node.js, Python, Go, etc)
  3. When a trace is detected, sends it to Claude for AI analysis
  4. Streams back the root cause, explanation, and fix suggestion
  5. Your process continues running — analysis is non-blocking
Basic Usage

Start by wrapping any process with votrio:

votrio run "npm start"

When an error occurs, you'll see:

Example output
$ votrio run "npm start"

● votrio watching — node v20.11.0
● AI trace analysis enabled

  > myapp@1.0.0 start
  > node index.js

Server listening on :3000

TypeError: Cannot read properties of undefined (reading 'id')
    at /src/routes/user.ts:42:18
    at Layer.handle [as handle_request] (/node_modules/express/lib/router/layer.js:95:16)

──────────────────────────────────────────────────────────────────
● votrio — trace analysis

  Root cause: req.user is undefined because the authentication middleware
             didn't run before this route handler.

  Why: Express middleware order matters. The auth middleware must come
       before route definitions. If auth is loaded after routes, req.user
       won't exist when routes execute.

  Fix: Move require("./middleware/auth") before require("./routes") in
       your app.js, or use app.use(authMiddleware) before app.use(routes).

  Confidence: 94%
──────────────────────────────────────────────────────────────────
Supported Languages

Votrio can analyze stack traces from:

Node.js / JavaScript

Full support for TypeScript too

Python

Traceback format recognized

Go

goroutine panic traces

Rust

backtrace module format

Java

Exception traces supported

C / C++

Stack traces with line info

Command-Line Options
--no-ai

Disable AI analysis. Votrio will just pipe output through without analyzing traces.

votrio run --no-ai "npm start"
--model <model>

Specify which Anthropic model to use for analysis (default: claude-sonnet-4-20250514)

votrio run --model claude-opus-4-1 "npm start"
--verbose

Show debug information from votrio itself (useful for troubleshooting)

votrio run --verbose "npm start"
Configuration

Control trace analysis behavior via votrio.config.mjs:

export default defineConfig({
  model: "claude-sonnet-4-20250514",
  
  traces: {
    enabled: true,        // Enable/disable trace analysis
    minConfidence: 70,    // Only show explanations with 70%+ confidence
    showFix: true,        // Include fix suggestions
  },
});

See the Configuration page for complete options.

Common Patterns Detected

Votrio recognizes and explains patterns like:

  • Null/undefined reference errors
  • Type mismatch errors
  • Missing dependencies or modules
  • Async/await issues (promise rejections)
  • Memory exhaustion or out-of-bounds access
  • Permission and file system errors
  • Network timeout or connection errors
  • Database query failures
Requirements
  • Anthropic API Key: Run votrio auth to configure
  • Node.js 18+: Votrio itself requires Node 18 or later
  • Internet connection: AI analysis requires calls to Anthropic API
Troubleshooting

Trace not being analyzed?

Make sure traces are enabled in your config and your API key is set: votrio auth

Analysis taking too long?

Use a faster model like claude-haiku-3.5 with --model claude-haiku-3.5

Running out of API quota?

Use votrio run --no-ai to disable AI features, or run with --verbose to see API usage