aitbc/docs/user/guides/troubleshooting.md

Troubleshooting Guide

Common issues and solutions when using the AITBC network.

Job Issues

Job Stuck in "Pending" State

Symptoms: Job submitted but stays in pending for a long time.

Causes:

• No miners currently available
• Network congestion
• Model not supported by available miners

Solutions:

1. Wait a few minutes - miners may become available
2. Check network status at Explorer
3. Try a different model (e.g., llama3.2:1b instead of llama3.2)
4. Cancel and resubmit during off-peak hours

# Check job status
./aitbc-cli.sh status <job_id>

# Cancel if needed
./aitbc-cli.sh cancel <job_id>

Job Failed

Symptoms: Job status shows failed with an error message.

Common Errors:

Error	Cause	Solution
Model not found	Invalid model name	Check available models
Prompt too long	Input exceeds limit	Shorten your prompt
Timeout	Job took too long	Reduce max_tokens or simplify prompt
Miner disconnected	Miner went offline	Resubmit job
Insufficient balance	Not enough AITBC	Top up your balance

Unexpected Output

Symptoms: Job completed but output is wrong or truncated.

Solutions:

1. Truncated output: Increase max_tokens parameter
2. Wrong format: Be more specific in your prompt
3. Gibberish: Lower temperature (try 0.3-0.5)
4. Off-topic: Rephrase prompt to be clearer

Connection Issues

Cannot Connect to API

Symptoms: Connection refused or timeout errors.

Solutions:

1. Check your internet connection
2. Verify API URL: https://aitbc.bubuit.net/api
3. Check if service is up at Explorer
4. Try again in a few minutes

# Test connectivity
curl -I https://aitbc.bubuit.net/api/health

Authentication Failed

Symptoms: 401 Unauthorized or Invalid API key errors.

Solutions:

1. Verify your API key is correct
2. Check if API key has expired
3. Ensure API key has required permissions
4. Generate a new API key if needed

Wallet Issues

Cannot Connect Wallet

Symptoms: Wallet connection fails or times out.

Solutions:

1. Ensure browser extension is installed and unlocked
2. Refresh the page and try again
3. Check if wallet is on correct network
4. Clear browser cache and cookies

Transaction Not Showing

Symptoms: Sent tokens but balance not updated.

Solutions:

1. Wait for confirmation (may take a few minutes)
2. Check transaction in Explorer
3. Verify you sent to correct address
4. Contact support if still missing after 1 hour

Insufficient Balance

Symptoms: Insufficient balance error when submitting job.

Solutions:

1. Check your current balance
2. Top up via Exchange
3. Wait for pending deposits to confirm

CLI Issues

Command Not Found

Symptoms: aitbc-cli.sh: command not found

Solutions:

# Make script executable
chmod +x aitbc-cli.sh

# Run with explicit path
./aitbc-cli.sh status

# Or add to PATH
export PATH=$PATH:$(pwd)

Permission Denied

Symptoms: Permission denied when running CLI.

Solutions:

chmod +x aitbc-cli.sh

SSL Certificate Error

Symptoms: SSL certificate problem or certificate verify failed

Solutions:

# Update CA certificates
sudo apt update && sudo apt install ca-certificates

# Or skip verification (not recommended for production)
curl -k https://aitbc.bubuit.net/api/health

Performance Issues

Slow Response Times

Symptoms: Jobs take longer than expected.

Causes:

• Large prompt or output
• Complex model
• Network congestion
• Miner hardware limitations

Solutions:

1. Use smaller models for simple tasks
2. Reduce max_tokens if full output not needed
3. Submit during off-peak hours
4. Use streaming for faster first-token response

Rate Limited

Symptoms: 429 Too Many Requests error.

Solutions:

1. Wait before retrying (check Retry-After header)
2. Reduce request frequency
3. Use exponential backoff in your code
4. Request higher rate limits if needed

Getting Help

Self-Service Resources

• Documentation: https://aitbc.bubuit.net/docs/
• API Reference: https://aitbc.bubuit.net/api/docs
• Explorer: https://aitbc.bubuit.net/explorer/

Reporting Issues

When reporting an issue, include:

1. Job ID (if applicable)
2. Error message (exact text)
3. Steps to reproduce
4. Expected vs actual behavior
5. Timestamp of when issue occurred

Debug Mode

Enable verbose logging for troubleshooting:

# CLI debug mode
DEBUG=1 ./aitbc-cli.sh submit "test"

# Python SDK
import logging
logging.basicConfig(level=logging.DEBUG)