Skip to main content
Common issues and solutions.

​
Connection Issues

​
“No API token configured” Error

Cause: No active profile in auth.ini and no --token / CONTREE_TOKEN override. Solution (recommended): install contree-cli and run contree auth: 
uv tool install contree-cli   # or: pip install contree-cli
contree auth                  # interactive setup
This writes ~/.config/contree/auth.ini. The MCP server reads it automatically. For a one-off override: 
export CONTREE_TOKEN="your-token"
export CONTREE_URL="https://api.tokenfactory.nebius.com/sandboxes"
export CONTREE_PROJECT="your-nebius-project-id"   # only for IAM auth

​
Server logs Ignoring NEBIUS_API_KEY: NEBIUS_AI_PROJECT is not set

Cause: Your shell has NEBIUS_API_KEY set (typically for the Nebius SDK or terraform provider) but no NEBIUS_AI_PROJECT. The MCP server treats this as an incomplete IAM credential and falls back to the active profile from auth.ini. This is not an error — it’s a deliberate guard against an ambient env var hijacking your saved profile. Solution: nothing to do if you wanted the profile to load. If you meant to authenticate via env, also export NEBIUS_AI_PROJECT (or use the MCP-specific CONTREE_TOKEN / CONTREE_PROJECT, which layer per-field on top of the profile and don’t have this guard).

​
“IAM auth requires a project ID” Error

Cause: The active profile (or the env/CLI overrides) is IAM-typed but no project ID was supplied. Solution: either add project = ... under the matching [profile:<name>] section, set CONTREE_PROJECT, or pass --project <id>. For legacy JWT deployments, set type = jwt in the profile — projects aren’t needed there.

​
“Connection refused” Error

Cause: Server not reachable or wrong URL. Solution: Verify the URL in the active profile (or pass --url/CONTREE_URL): 
export CONTREE_URL="https://api.tokenfactory.nebius.com/sandboxes"

​
“Forbidden” / Missing Permissions

Cause: The active token doesn’t have the permission your call needs (spawn, import, set_image_tag, cancel, …). Solution: ask the whoami tool to enumerate what’s available: 
{"tool": "whoami"}
If a permission is false, the only recourse is a token with different grants — the MCP server cannot escalate.

​
Tool Errors

​
“Image not found”

Cause: Invalid image UUID or tag. Solutions:
  1. Check with list_images
  2. Ensure the UUID is correct
  3. For tags, use tag: prefix: "image": "tag:python:3.11"

​
“Directory state not found”

Cause: Invalid directory_state_id or expired session. Solution: Call rsync again to get a new directory_state_id.

​
“Operation timed out”

Cause: Command exceeded timeout. Solution: Increase the timeout: 
{"tool": "run", "args": {
  "command": "...",
  "timeout": 600
}}

​
Performance Issues

​
Slow File Sync

Cause: Large files or too many files. Solutions:
  1. Use exclusions: 
    {"exclude": ["node_modules", ".git", "__pycache__", "*.log"]}
  2. Sync only what you need
  3. Use glob patterns for specific files

​
Commands Taking Long to Start

Cause: VM startup time (~2-5 seconds). Solutions:
  1. Batch operations when possible
  2. Use async for parallel operations
  3. Reuse images with dependencies pre-installed

​
Debugging

​
Enable Debug Logging

Pass --log-level debug to the server: 
contree-mcp --log-level debug ...
In an MCP client config that spawns the server, append the flag to args: 
{
  "mcpServers": {
    "contree": {
      "command": "uvx",
      "args": ["contree-mcp", "--log-level", "debug"]
    }
  }
}

​
Confirm the Installed Version

contree-mcp --version (or -V) prints the User-Agent the server emits on every backend call. Useful when triaging which build is actually wired into your client: 
$ contree-mcp --version
contree-mcp/0.1.1 Python/3.13.0.final.0 Linux-6.5.0-arm64

​
Check Operation Status

For async operations: 
{"tool": "get_operation", "args": {"operation_id": "op-..."}}

​
View Image Lineage

To understand how an image was created: 
contree://image/your-image-uuid/lineage

​
Getting Help