Skip to main content

​
Troubleshooting

This guide helps you resolve common issues with A24Z.

​
Installation Issues

​
CLI Installation Fails

Problem: npm install -g a24z fails Solutions:
Error: EACCES: permission deniedSolution 1: Use sudo (macOS/Linux)
sudo npm install -g a24z
Solution 2: Configure npm prefix (Recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH'-~/.bashrc
source ~/.bashrc
npm install -g a24z
Error: ETIMEDOUT or ENOTFOUNDSolutions:
  • Check your internet connection
  • Try a different registry: 
    npm install -g a24z --registry=https://registry.npmjs.org/
  • Use a VPN if behind a firewall
  • Increase timeout: 
    npm install -g a24z --fetch-timeout=60000
Error: Unsupported engineSolution: Upgrade Node.js to 18+
# Check current version
node --version

# Install latest LTS
# macOS: brew install node
# Linux: nvm install --lts
# Windows: Download from nodejs.org

​
Authentication Issues

​
Login Fails

Problem: a24z login doesn’t work
1

Check Internet Connection

Ensure you can reach api.a24z.ai:
curl https://api.a24z.ai/health
2

Clear Old Configuration

Remove existing config:
rm -rf ~/.a24z
3

Try Again

a24z login
4

Manual Token Entry

If browser doesn’t open:
  1. Copy the URL from terminal
  2. Open in browser manually
  3. Complete authentication

​
Invalid API Key

Problem: 401 Unauthorized errors Checks:
  1. Verify key is active:
  2. Check key format: 
    # Should start with sk_live_ or sk_test_
echo $A24Z_API_KEY
  3. Regenerate key: 
    a24z login

​
Hook Installation Issues

​
Hooks Not Firing

Problem: Events not appearing in dashboard Diagnosis: 
# Check installation status
a24z status

# Expected output:
# ✅ A24Z CLI is properly configured
# ✅ Authentication: Valid
# ✅ Claude Code: Hooks installed
# ✅ API Connection: Healthy
Solutions:
Solution: Install hooks
a24z install claude-code
Verify ~/.claude/settings.json was updated.
Check:
which a24z
Solution: Add to PATH
echo 'export PATH="$HOME/.npm-global/bin:$PATH"'-~/.bashrc
source ~/.bashrc
Check: View Claude Code settings
cat ~/.claude/settings.json
Solution: Reinstall
a24z install claude-code --force

​
Data Not Appearing

Problem: Using tools but no data in dashboard Wait Time: Data can take 30-60 seconds to appear. Checks:
  1. Check API connectivity: 
    a24z status
  2. View logs (if debug enabled): 
    tail -f ~/.claude/a24z.log
  3. Test with simple command: Use a simple tool in Claude Code and wait 1 minute
  4. Check dashboard filters:
    • Ensure correct time range selected
    • Verify organization is correct
    • Clear any filters

​
Performance Issues

​
Slow Tool Execution

Problem: Tools taking longer than expected Checks:
  1. Network latency: 
    ping api.a24z.ai
  2. API response time: Check dashboard for API latency metrics
Solutions:
  • Reduce context: Smaller prompts = faster execution
  • Check internet: Ensure stable connection
  • Contact support: If latency > 500ms

​
High Token Usage

Problem: Unexpectedly high costs Solutions:
  1. Review sessions:
    • Check dashboard for high-usage sessions
    • Identify what’s consuming tokens
  2. Optimize prompts:
    • Remove unnecessary context
    • Use file references instead of pasting code
    • Clear conversation history regularly
  3. Set alerts: Configure budget alerts in dashboard

​
Dashboard Issues

​
Can’t Access Dashboard

Problem: Can’t log in to app.a24z.ai Solutions:
  1. Check credentials:
    • Verify email/password
    • Try password reset
  2. Check organization:
    • Ensure you’re invited to an organization
    • Ask admin to check your access
  3. Clear browser cache: 
    Ctrl+Shift+Delete (Chrome/Firefox)

​
Data Not Loading

Problem: Dashboard shows no data Checks:
  1. Time range: Adjust to include your activity
  2. Organization: Ensure correct org selected
  3. Filters: Clear all filters
  4. Browser: Try incognito mode or different browser

​
CLI Issues

​
Command Not Found

Problem: a24z: command not found Solutions:
  1. Verify installation: 
    npm list -g a24z
  2. Add to PATH: 
    export PATH="$(npm config get prefix)/bin:$PATH"
  3. Reinstall: 
    npm uninstall -g a24z
npm install -g a24z

​
Version Mismatch

Problem: Features not working as documented Check version: 
a24z --version
Update: 
npm update -g a24z

​
Organization Issues

​
Can’t Switch Organizations

Problem: a24z org switch fails Checks:
  1. List organizations: 
    a24z org list
  2. Verify membership: Check dashboard for organization access
Solution:
  • Ask organization admin to invite you
  • Ensure you accepted the invitation

​
Wrong Organization Data

Problem: Seeing another organization’s data This is a serious security issue! Action:
  1. Immediately log out
  2. Clear all credentials: 
    rm -rf ~/.a24z
  3. Report to [email protected]
  4. Log in again with a24z login

​
Getting More Help

​
Check Status

Always start with: 
a24z status

​
Enable Debug Mode

For detailed logs: 
export A24Z_DEBUG=true
a24z status

​
Collect Diagnostic Info

# System info
node --version
npm --version
a24z --version

# Configuration
cat ~/.a24z/config.json | jq .

# Claude Code settings (if applicable)
cat ~/.claude/settings.json | jq .

​
Contact Support

If issues persist:

​
Common Error Messages

​
”Organization access required”

Cause: Trying to access data without organization membership Solution: Get invited to an organization or create one

​
”Invalid API key”

Cause: Key is revoked, expired, or incorrect Solution: Run a24z login to get new key

​
”Rate limit exceeded”

Cause: Too many requests in short period Solution: Wait 60 seconds and retry

​
”Tool not found”

Cause: Trying to install hooks for unsupported tool Solution: Check supported tools with a24z --help

​
”Failed to connect to ClickHouse”

Cause: Dashboard cannot query analytics database Solution:
  1. Check if this is a temporary outage at status.a24z.ai
  2. Refresh the page
  3. If persists, contact [email protected]

​
”Session not found”

Cause: Trying to view a session that doesn’t exist or was deleted Solutions:
  • Verify the session ID is correct
  • Check if session is within data retention period
  • Ensure you have access to the organization

​
”Tool execution timeout”

Cause: Tool took too long to execute Solutions:
  • Check if the task is too complex
  • Verify network connectivity
  • Try breaking down the task into smaller steps

​
Tool-Specific Issues

​
Claude Code Issues

Problem: Hooks not capturing data in Claude Code Diagnosis: 
# Check hook installation
cat ~/.claude/settings.json

# Look for A24Z hooks
grep -A 5 "a24z" ~/.claude/settings.json
Solutions:
  1. Reinstall hooks: 
    a24z install claude-code --force
  2. Verify CLI is accessible: 
    which a24z
# Should return path like /usr/local/bin/a24z
  3. Check hook execution permissions: 
    ls -la $(which a24z)
# Should have execute permissions (rwxr-xr-x)
  4. Test hook manually: 
    a24z hook --type PreToolUse --data '{"tool":"test"}'
# Should succeed without errors

​
Gemini CLI Issues

Problem: Gemini CLI data not appearing Solutions:
  1. Ensure latest Gemini CLI version
  2. Verify environment variables are set
  3. Check OTLP exporter configuration

​
Token Tracking Issues

Problem: Token counts seem incorrect Common Causes:
  1. Caching: Some responses are cached and don’t use tokens
  2. Streaming: Streaming responses may show estimates
  3. Model differences: Different models have different tokenization
Verification: 
# Check raw token data
a24z api metrics --detailed --session <session-id>

​
Cost Calculation Issues

Problem: Costs don’t match expectations Checks:
  1. Model pricing: Verify you’re using expected model
  2. Input vs Output: Output tokens cost more
  3. Time period: Ensure correct date range
  4. Rate changes: Model pricing can change
Get exact costs:
  • View session details in dashboard
  • Export cost report
  • Check model pricing at provider’s website

​
Dashboard-Specific Issues

​
Metrics Not Updating

Problem: Dashboard shows stale data Solutions:
  1. Force refresh:
    • Click refresh button
    • Or press Ctrl+R (Cmd+R on Mac)
  2. Clear cache: 
    # In browser, open DevTools (F12)
# Right-click refresh → "Empty Cache and Hard Reload"
  3. Check time range:
    • Ensure “Last 24 hours” or “Last 7 days” is selected
    • Try “Custom range” with explicit dates

​
Graphs Not Loading

Problem: Blank charts or “Loading…” forever Solutions:
  1. Check browser console:
    • Open DevTools (F12)
    • Look for errors in Console tab
    • Report any errors to support
  2. Disable ad blockers:
    • Some ad blockers interfere with analytics
    • Try disabling temporarily
  3. Try different browser:
    • Test in Chrome, Firefox, or Safari
    • Use incognito/private mode

​
Filters Not Working

Problem: Applying filters doesn’t change results Solutions:
  1. Clear all filters first:
    • Click “Clear Filters” button
    • Apply one filter at a time
  2. Check for data:
    • Ensure filtered data exists
    • Try broader filters
  3. Verify time range:
    • Filters apply within selected time range
    • Expand time range if needed

​
Performance Optimization

​
Reducing Latency

For low latency:
  1. Use local buffering: 
    // ~/.a24z/config.json
{
  "buffer": {
    "enabled": true,
    "maxSize": 1000,
    "flushInterval": 5000
  }
}
  2. Batch events:
    • Events are batched automatically
    • Adjust batch size if needed
  3. Use async mode:
    • All hooks are async by default
    • No blocking operations

​
Reducing Token Usage

Strategies:
  1. Optimize context:
    • Remove unnecessary files from context
    • Use specific file references
    • Clear conversation history regularly
  2. Use smaller models:
    • Switch to smaller models for simple tasks
    • Reserve large models for complex work
  3. Leverage caching:
    • Repeated queries may use cached responses
    • Reduces token consumption

​
Reducing Costs

Cost optimization:
  1. Monitor usage:
    • Set up cost alerts
    • Review top users/teams weekly
    • Identify high-cost sessions
  2. Budget controls: 
    # Set monthly budget (dashboard)
# Gets alerts at 50%, 75%, 90%, 100%
  3. Training:
    • Train team on efficient prompting
    • Share best practices
    • Review high-cost sessions together

​
Network & Connectivity

​
Firewall Issues

Problem: Can’t connect to A24Z API Whitelist these domains: 
api.a24z.ai
app.a24z.ai
*.a24z.ai
Ports:
  • HTTPS: 443
  • WebSocket: 443
Corporate Proxy: 
# Set proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Or in ~/.a24z/config.json
{
  "proxy": "http://proxy.company.com:8080"
}

​
VPN Issues

Problem: A24Z doesn’t work on VPN Solutions:
  1. Split tunnel: Configure VPN to exclude a24z.ai
  2. Whitelist: Add a24z.ai to VPN allowlist
  3. DNS: Use public DNS (8.8.8.8) to bypass VPN DNS

​
Slow API Response

Problem: API calls taking >2 seconds Diagnosis: 
# Test API latency
time curl -H "x-api-key: $A24Z_API_KEY" \
  https://api.a24z.ai/health
Solutions:
  1. Check region: Ensure using closest region
  2. Network quality: Test with fast.com or speedtest.net
  3. Contact support: If consistently >1s, we can investigate

​
Data & Privacy Issues

​
GDPR Data Request

To request your data:
  1. Email [email protected] with:
    • Your email address
    • Organization name
    • Data type requested (all data, specific sessions, etc.)
  2. We’ll respond within 30 days with:
    • Data export (JSON format)
    • Verification of your identity

​
Data Deletion Request

To delete your data:
  1. In dashboard: Settings → Privacy → Delete My Data
  2. Or email [email protected]
What gets deleted:
  • All telemetry data
  • Sessions and metrics
  • User profile (if account closed)
Retention:
  • Deletion is permanent after 30 days
  • Audit logs retained per legal requirements

​
Compliance Questions

For compliance inquiries:

​
Common Error Messages

​
”Organization access required”

Cause: Trying to access data without organization membership Solution: Get invited to an organization or create one

​
”Invalid API key”

Cause: Key is revoked, expired, or incorrect Solution: Run a24z login to get new key

​
”Rate limit exceeded”

Cause: Too many requests in short period Solution: Wait 60 seconds and retry

​
”Tool not found”

Cause: Trying to install hooks for unsupported tool Solution: Check supported tools with a24z --help

​
Preventive Measures

​
Regular Maintenance

# Update CLI monthly
npm update -g a24z

# Rotate API keys quarterly
# (via dashboard)

# Check status weekly
a24z status

​
Best Practices

  • Keep Node.js updated
  • Monitor token usage
  • Review failed executions
  • Keep hooks configured correctly

​
Still Having Issues?

FAQ

Check frequently asked questions

Community

Ask the community

Email Support

Contact our support team

GitHub Issues

Report a bug