Troubleshooting

Common issues and solutions when using Claudible.

Diagnostic Tool

Run our diagnostic script to automatically check your Claudible configuration and connectivity.

macOS / Linux

curl -fsSL "https://claudible.io/doctor.sh?key=YOUR_KEY" | sh

Windows (PowerShell)

irm "https://claudible.io/doctor.ps1?key=YOUR_KEY" | iex

Usage Options

# Test with specific API key
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --key YOUR_KEY

# Offline mode (skip network tests)
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --offline

# Verbose output
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --verbose

# JSON output for automation
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --json

Connection Issues

Error: "Connection refused" or "Network error"

• Check your internet connection
• Verify ANTHROPIC_BASE_URL is set to https://claudible.io
• Check if your firewall blocks outgoing connections

Error: "Unauthorized" or "Invalid API key"

• Verify your API key is correct
• Check if the key is expired or disabled
• Make sure ANTHROPIC_AUTH_TOKEN is set

echo $ANTHROPIC_AUTH_TOKEN  # Check if key is set

Model Issues

Error: "Model not found"

• Use correct model names from curl https://claudible.io/v1/models
• Check available models: curl https://claudible.io/v1/models

Error: "Insufficient balance"

• Check your balance in the Dashboard
• Contact support to add credits

Configuration Issues

Changes not taking effect

• Restart your terminal after changing environment variables
• Run source ~/.bashrc or source ~/.zshrc
• Verify settings: cat ~/.claude/settings.json

settings.json syntax error

Validate your JSON at jsonlint.com. Common mistakes:

• Missing quotes around keys
• Trailing comma after last property
• Using single quotes instead of double quotes

Claude Code Issues

Claude Code not using Claudible

Check if environment variables are set correctly:

echo $ANTHROPIC_BASE_URL    # Should be: https://claudible.io
echo $ANTHROPIC_AUTH_TOKEN  # Should be your API key

Reset to default configuration

# Uninstall Claudible config
curl -fsSL "https://claudible.io/uninstall.sh" | sh

# Reinstall
curl -fsSL "https://claudible.io/install.sh?key=YOUR_KEY" | sh

Statusline Issues

Statusline not showing

• Verify the script exists: ls ~/.claude/scripts/statusline.sh
• Check ~/.claude/settings.json has statusline enabled
• Restart Claude Code after configuration changes

Balance not updating

• Balance is cached for 30 seconds to reduce API calls
• Check your API key is configured correctly
• Verify network connectivity: curl https://claudible.io/v1/models

Statusline showing errors

• Check script permissions: chmod +x ~/.claude/scripts/statusline.sh
• Test script manually: ~/.claude/scripts/statusline.sh
• Check for missing dependencies (curl, jq)

MCP Server Issues

MCP Answer Engine not working

• Verify the MCP server is added: claude mcp list
• Check your API key is included in the Authorization header
• Test the endpoint: curl -H "Authorization: Bearer YOUR_KEY" https://claudible.io/mcp/answer-engine

Error: "MCP server not responding"

• Check your internet connection
• Remove and re-add the MCP server:

claude mcp remove my-answer-engine
claude mcp add --transport http --scope user \
  my-answer-engine https://claudible.io/mcp/answer-engine \
  --header "Authorization: Bearer YOUR_KEY"

Windows-Specific Issues

PowerShell script execution blocked

If you see "script execution is disabled", run PowerShell as Administrator and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Environment variables not persisting

On Windows, environment variables set in PowerShell don't persist. Add them permanently:

# Set permanently for current user
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://claudible.io", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "YOUR_KEY", "User")

Then restart your terminal.

Path issues with backslashes

• Use forward slashes / or escaped backslashes \\ in paths
• The Claude config folder is at %USERPROFILE%\.claude\

Still Need Help?

Contact us on Telegram or check the FAQ for common questions.

Xử lý sự cố

Các vấn đề thường gặp và cách giải quyết khi sử dụng Claudible.

Công cụ chẩn đoán

Chạy script chẩn đoán để tự động kiểm tra cấu hình và kết nối Claudible.

macOS / Linux

curl -fsSL "https://claudible.io/doctor.sh?key=YOUR_KEY" | sh

Windows (PowerShell)

irm "https://claudible.io/doctor.ps1?key=YOUR_KEY" | iex

Tùy chọn sử dụng

# Kiểm tra với API key cụ thể
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --key YOUR_KEY

# Chế độ offline (bỏ qua kiểm tra mạng)
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --offline

# Kết quả chi tiết
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --verbose

# Kết quả JSON cho tự động hóa
curl -fsSL "https://claudible.io/doctor.sh" | sh -s -- --json

Vấn đề kết nối

Lỗi: "Connection refused" hoặc "Network error"

• Kiểm tra kết nối internet
• Xác nhận ANTHROPIC_BASE_URL được đặt là https://claudible.io
• Kiểm tra firewall có chặn kết nối ra ngoài không

Lỗi: "Unauthorized" hoặc "Invalid API key"

• Xác nhận API key đúng
• Kiểm tra key có hết hạn hoặc bị vô hiệu hóa không
• Đảm bảo ANTHROPIC_AUTH_TOKEN đã được thiết lập

echo $ANTHROPIC_AUTH_TOKEN  # Kiểm tra key đã được thiết lập

Vấn đề model

Lỗi: "Model not found"

• Dùng đúng tên model từ curl https://claudible.io/v1/models
• Kiểm tra model có sẵn: curl https://claudible.io/v1/models

Lỗi: "Insufficient balance"

• Kiểm tra balance trong Dashboard
• Liên hệ hỗ trợ để nạp thêm credit

Vấn đề cấu hình

Thay đổi không có hiệu lực

• Khởi động lại terminal sau khi thay đổi biến môi trường
• Chạy source ~/.bashrc hoặc source ~/.zshrc
• Xác nhận settings: cat ~/.claude/settings.json

Lỗi cú pháp settings.json

Kiểm tra JSON tại jsonlint.com. Lỗi thường gặp:

• Thiếu dấu ngoặc kép quanh key
• Dấu phẩy thừa sau thuộc tính cuối
• Dùng dấu ngoặc đơn thay vì ngoặc kép

Vấn đề Claude Code

Claude Code không dùng Claudible

Kiểm tra biến môi trường đã thiết lập đúng:

echo $ANTHROPIC_BASE_URL    # Phải là: https://claudible.io
echo $ANTHROPIC_AUTH_TOKEN  # Phải là API key của bạn

Reset về cấu hình mặc định

# Gỡ cấu hình Claudible
curl -fsSL "https://claudible.io/uninstall.sh" | sh

# Cài đặt lại
curl -fsSL "https://claudible.io/install.sh?key=YOUR_KEY" | sh

Vấn đề Statusline

Statusline không hiển thị

• Kiểm tra script tồn tại: ls ~/.claude/scripts/statusline.sh
• Kiểm tra ~/.claude/settings.json đã bật statusline
• Khởi động lại Claude Code sau khi thay đổi cấu hình

Balance không cập nhật

• Balance được cache 30 giây để giảm số lần gọi API
• Kiểm tra API key đã được cấu hình đúng
• Kiểm tra kết nối mạng: curl https://claudible.io/v1/models

Statusline hiển thị lỗi

• Kiểm tra quyền script: chmod +x ~/.claude/scripts/statusline.sh
• Chạy thử script thủ công: ~/.claude/scripts/statusline.sh
• Kiểm tra dependency thiếu (curl, jq)

Vấn đề MCP Server

MCP Answer Engine không hoạt động

• Xác nhận MCP server đã được thêm: claude mcp list
• Kiểm tra API key có trong Authorization header
• Kiểm tra endpoint: curl -H "Authorization: Bearer YOUR_KEY" https://claudible.io/mcp/answer-engine

Lỗi: "MCP server not responding"

• Kiểm tra kết nối internet
• Xóa và thêm lại MCP server:

claude mcp remove my-answer-engine
claude mcp add --transport http --scope user \
  my-answer-engine https://claudible.io/mcp/answer-engine \
  --header "Authorization: Bearer YOUR_KEY"

Vấn đề trên Windows

PowerShell chặn chạy script

Nếu thấy "script execution is disabled", chạy PowerShell với quyền Administrator và thực thi:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Biến môi trường không được lưu

Trên Windows, biến môi trường đặt trong PowerShell không được lưu vĩnh viễn. Thêm vĩnh viễn:

# Thiết lập vĩnh viễn cho user hiện tại
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://claudible.io", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "YOUR_KEY", "User")

Sau đó khởi động lại terminal.

Vấn đề đường dẫn với dấu backslash

• Dùng dấu gạch chéo / hoặc dấu backslash thoát \\ trong đường dẫn
• Thư mục Claude config nằm ở %USERPROFILE%\.claude\

Vẫn cần hỗ trợ?

Liên hệ qua Telegram hoặc xem FAQ cho các câu hỏi thường gặp.