Skip to content

Troubleshooting

Log Files

Logs are stored at:

~/.local/share/altimate-code/log/

Enable verbose logging:

altimate --print-logs --log-level DEBUG

Common Issues

Provider Connection Failed

Symptoms: "Failed to connect to provider" or timeout errors.

Solutions:

  1. Verify your API key is set: 
    echo $ANTHROPIC_API_KEY
  2. Check network connectivity to the provider
  3. If behind a proxy, set HTTPS_PROXY (see Network)
  4. Try a different provider to isolate the issue

Provider API Errors

Symptoms: APIError: <status>: <message> shown in chat output. Common forms:

  • APIError: Bad Request: The model 'foo' does not exist or you do not have access to it.
  • APIError: Unauthorized: Invalid API key
  • APIError: Rate limit exceeded

As of v0.7.1, altimate-code surfaces the inner provider message instead of dumping the raw JSON body. The status prefix (Bad Request:, Unauthorized:, etc.) comes from the provider's HTTP status code; everything after the colon is the provider's text verbatim.

Solutions by error class:

  1. Model not found (APIError: Bad Request: The model '<name>' does not exist...) — list the models your provider currently exposes and re-run with one of them: 
    altimate models <provider>
    model_not_found errors no longer auto-retry; the message you see is the first attempt, not the fifth.
  2. Unauthorized / 401 — re-run altimate auth login <provider> and re-issue the request.
  3. Rate limited / 429 — altimate-code automatically retries on rate-limit responses (including plain-text 429s from Alibaba/DashScope). If you keep hitting rate limits, lower parallel_tool_calls or switch to a less-saturated model.
  4. Context overflow — switch to a larger-context model or trim earlier turns with /compact. Detection covers Anthropic, Bedrock, OpenAI, Gemini, xAI, Groq, OpenRouter, DeepSeek, Copilot, llama.cpp, LM Studio, MiniMax, Kimi, Moonshot, Azure OpenAI, and HTTP 413.
  5. HTML page returned — usually a gateway/proxy error. The CLI returns a friendly hint pointing at altimate auth login rather than dumping the raw HTML.

Privacy note: error messages flow through the same redaction layer as everything else (sk-…, Bearer …, email addresses, and *.local / *.internal / RFC1918 / IPv6 loopback / ULA / link-local / AWS IMDS hostnames are masked before reaching telemetry). Internal-host URLs in metadata.url are also redacted before they reach local storage or shared sessions, and basic-auth userinfo (user:pass@…) is stripped from every URL regardless of whether the host is internal.

Tool Execution Errors

Symptoms: "No native handler" or tool execution failures for data engineering tools.

Solutions:

  1. Ensure @altimateai/altimate-core is installed (should be automatic): 
    npm ls @altimateai/altimate-core
  2. For database tools, ensure the required driver is installed: 
    # Example for Snowflake:
bun add snowflake-sdk
# Example for PostgreSQL:
bun add pg
  3. No Python installation is required. All tools run natively in TypeScript.

Warehouse Connection Failed

Symptoms: "Connection refused", authentication errors, or "No warehouse configured".

Solutions:

  1. If using dbt: Run /discover — it automatically finds your profiles.yml from DBT_PROFILES_DIR, your project directory, or <home>/.dbt/profiles.yml. If your profiles.yml is in a custom location, set DBT_PROFILES_DIR to the directory containing it.
  2. If not using dbt: Add a connection via the warehouse_add tool, ~/.altimate-code/connections.json, or ALTIMATE_CODE_CONN_* env vars.
  3. Test connectivity: use the warehouse_test tool with your connection name.
  4. Check that the warehouse hostname and port are reachable
  5. Verify the role/user has the required permissions
  6. For Snowflake: ensure the warehouse is not suspended
  7. For BigQuery: check that the service account has the required IAM roles

MCP Server Initialization Failures

Symptoms: MCP tools missing or MCP server not available after startup.

Solutions:

  1. Check the log files. MCP initialization errors are now logged with the server name and error message: 
    WARN failed to initialize MCP server { key: "my-tools", error: "..." }
  2. Verify the MCP server command is correct in your config
  3. Test the server manually: 
    altimate mcp test my-tools
  4. Check that required environment variables are set (e.g., API keys referenced in the MCP config)

LSP Server Won't Start

Symptoms: No diagnostics or completions for a language.

Solutions:

  1. Check if the LSP server is disabled: 
    { "lsp": { "typescript": { "disabled": false } } }
  2. Enable LSP auto-download: 
    unset ALTIMATE_CLI_DISABLE_LSP_DOWNLOAD
  3. Check the log files for LSP-specific errors

Auto-Update Issues

Disable auto-update if it causes problems:

export ALTIMATE_CLI_DISABLE_AUTOUPDATE=true

Or set to notification only in your config:

{
  "autoupdate": "notify"
}

Both options still show an upgrade indicator in the footer when a new version is available. To upgrade manually, run:

altimate upgrade

Note

When an update is available, you'll see ↑ <version> update available · altimate upgrade in the bottom-right corner of the TUI.

Context Too Large

If conversations hit context limits:

{
  "compaction": {
    "auto": true,
    "prune": true
  }
}

Or manually compact in the TUI: leader + Shift+C.

Debug Mode

Run with full debug output:

altimate --print-logs --log-level DEBUG 2>debug.log

Then share debug.log when reporting issues.

Getting Help