Troubleshooting¶

Installation¶

Standalone binary not found after curl install¶

Symptoms: altimate-code: command not found after running curl -fsSL https://www.altimate.sh/install | bash.

As of v0.7.1 the curl-installed binary is named altimate, not altimate-code. The npm package continues to ship both names. If you scripted against the curl install:

# Before (v0.7.0 and earlier curl install):
~/.altimate-code/bin/altimate-code run "..."

# After (v0.7.1+ curl install):
~/.altimate/bin/altimate run "..."

Or stay on the altimate-code name by installing via npm: npm install -g altimate-code.

`Cannot find module '@altimateai/altimate-code-core'`¶

Symptoms: Binary crashes on first run with the above error (curl-installed v0.7.0 and earlier).

The v0.7.0 curl install shipped without the NAPI native module. Fixed in v0.7.1 — the native module is now embedded directly into the binary. Re-install with:

curl -fsSL https://www.altimate.sh/install | bash

Alpine Linux (musl) not supported¶

Symptoms: Alpine Linux (musl) is not currently supported by the standalone install during curl install, or altimate-code is not currently supported on Alpine Linux (musl) during npm install postinstall.

@altimateai/altimate-core has no NAPI prebuild for musl. Workarounds:

# Run the glibc binary under Alpine (recommended):
apk add gcompat

# Then either:
curl -fsSL https://www.altimate.sh/install | bash   # standalone binary
# or:
apk add gcompat && npm install -g altimate-code  # npm install

Or use a glibc-based base image (debian, ubuntu, node:slim).

Windows on ARM64 not supported¶

Symptoms: altimate-code is not currently built for Windows on ARM64 during install.

Run the x64 build under Windows-on-ARM's x64 emulation layer, or use WSL.

`altimate` not found after the Windows standalone install¶

Symptoms: altimate is unrecognized after running the PowerShell installer.

The installer adds %USERPROFILE%\.altimate\bin to your user PATH — open a new terminal so it takes effect. To (re)install or pin a version:

# Latest
powershell -c "irm https://www.altimate.sh/install.ps1 | iex"

# Specific version
&([scriptblock]::Create((irm https://www.altimate.sh/install.ps1))) -Version 1.0.180

If the binary crashes immediately on an older CPU, the installer normally retries the baseline (non-AVX2) build automatically; force it with -ForceBaseline.

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:

Verify your API key is set:
```
echo $ANTHROPIC_API_KEY
```
Check network connectivity to the provider
If behind a proxy, set HTTPS_PROXY (see Network)
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:

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.
Unauthorized / 401 — re-run altimate auth login <provider> and re-issue the request.
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.
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.
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:

Ensure @altimateai/altimate-core is installed (should be automatic):
```
npm ls @altimateai/altimate-core
```

For database tools, ensure the required driver is installed:

# Example for Snowflake:
bun add snowflake-sdk
# Example for PostgreSQL:
bun add pg

No Python installation is required. All tools run natively in TypeScript.

Plan mode refuses a benign request, or stops without exploring¶

Symptoms: In plan mode (--agent plan), the agent replies "I'm sorry, but I cannot assist with that request" to an ordinary planning ask, or you see the warning "the plan agent … stopped without calling any tools." Most common on the hosted altimate-default model (and other non-Anthropic models).

Solutions:

Upgrade to v0.8.3 or later. This was a known bug: altimate-code's internal plan instructions were delivered in a way that non-Anthropic models (GPT-5.x, Gemini, …) could mistake for a prompt-injection attempt and refuse. v0.8.3 delivers them as proper system-role messages, eliminating the refusal.
If you still see the agent stop without exploring, follow the in-product warning's recoveries: reply asking it to investigate first (read/grep/glob/explore), rephrase the request more concretely, or — if it keeps refusing — /model to a tier more eager to explore (e.g. Claude Sonnet/Opus).

Warehouse Connection Failed¶

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

Solutions:

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.
If not using dbt: Add a connection via the warehouse_add tool, ~/.altimate-code/connections.json, or ALTIMATE_CODE_CONN_* env vars.
Test connectivity: use the warehouse_test tool with your connection name.
Check that the warehouse hostname and port are reachable
Verify the role/user has the required permissions
For Snowflake: ensure the warehouse is not suspended
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:

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: "..." }
```
Verify the MCP server command is correct in your config
Test the server manually:
```
altimate mcp test my-tools
```
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:

Check if the LSP server is disabled:

{ "lsp": { "typescript": { "disabled": false } } }

Enable LSP auto-download:

unset ALTIMATE_CLI_DISABLE_LSP_DOWNLOAD

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¶

When something goes wrong that is hard to reproduce (a hang, Altimate Code closing unexpectedly, a connection that fails sometimes), turn on debug mode, reproduce the problem, then create a diagnostic report.

1. Turn on debug mode for the session where you will reproduce the problem:

# macOS / Linux
ALTIMATE_DEBUG=1 altimate

# Windows (PowerShell)
$env:ALTIMATE_DEBUG = "1"; altimate

In debug mode the log records every tool call as it starts and ends, and while one is running, a line every 15 seconds naming what is still in progress. Lines are written as they happen, so if Altimate Code hangs or closes, the log still shows what it was doing.

2. Create the report after the problem has happened:

altimate debug bundle

This writes altimate-debug-report-<time>.md in the current folder (use --output <path> to choose another place). It lists the problems it detected first, then the evidence: version and install method, operating system and terminal, warehouse connections (names, types, sign-in method and which fields are set, never values), MCP servers, a summary of the log, and the last 300 log lines. It also checks that the Snowflake and Databricks warehouses, the Altimate API, the telemetry endpoint (when telemetry is on) and the model catalogue this installation uses are reachable over HTTPS. Add --no-network (or --network=false) and the command makes no network requests at all, telemetry included. It does not start your project (plugins, language servers), so it still works when that is what hangs. The file is created readable only by you, where the filesystem supports it.

Passwords, keys, tokens and other secret settings (in name=value, JSON and connection-URL forms), email addresses, URL parameters, your home folder, your user name and your computer's name are removed. This is pattern-based and can miss a secret in an unusual format, so read the report before you send it. It stays on your machine until you send it to Altimate support yourself.

To save the raw logs to a file instead:

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

Getting Help¶

GitHub Issues: Report bugs and request features
Check existing issues before filing new ones

Troubleshooting¶

Installation¶

Standalone binary not found after curl install¶

Cannot find module '@altimateai/altimate-code-core'¶

Alpine Linux (musl) not supported¶

Windows on ARM64 not supported¶

altimate not found after the Windows standalone install¶

Log Files¶

Common Issues¶

Provider Connection Failed¶

Provider API Errors¶

Tool Execution Errors¶

Plan mode refuses a benign request, or stops without exploring¶

Warehouse Connection Failed¶

MCP Server Initialization Failures¶

LSP Server Won't Start¶

Auto-Update Issues¶

Context Too Large¶

Debug Mode¶

Getting Help¶

`Cannot find module '@altimateai/altimate-code-core'`¶

`altimate` not found after the Windows standalone install¶