Skip to content

Troubleshooting

This guide provides solutions to common issues encountered in the Bluefly LLM ecosystem.

Common Issues and Solutions

API Connection Issues

Issue: Cannot connect to BFAPI

Symptoms: - Connection refused errors - Timeout errors when making API requests

Solutions: 1. Verify that BFAPI is running: docker ps | grep bfapi 2. Check API logs for errors: docker logs bfapi 3. Ensure correct API URL in configuration 4. Check network connectivity and firewall settings

Issue: Authentication Failures

Symptoms: - 401 Unauthorized responses - Invalid token errors

Solutions: 1. Verify API key or credentials 2. Check token expiration 3. Ensure correct authentication headers 4. Reset credentials if necessary

Model Inference Problems

Issue: Model returns unexpected results

Symptoms: - Incorrect or nonsensical outputs - Incomplete responses

Solutions: 1. Check input formatting 2. Verify model version and parameters 3. Try different temperature or sampling settings 4. Check for context length issues

Issue: Model inference is slow

Symptoms: - Long response times - Timeouts during inference

Solutions: 1. Check server resource utilization 2. Reduce input size if possible 3. Check for resource contention 4. Consider scaling up inference resources

Installation and Setup Issues

Issue: Dependency installation failures

Symptoms: - npm or pip errors during installation - Missing dependencies in runtime

Solutions: 1. Clear cache: npm cache clean --force 2. Check Node.js version compatibility 3. Verify Python version for ML components 4. Check for conflicting dependencies

Issue: Docker containers failing to start

Symptoms: - Container exit immediately after starting - Container health checks failing

Solutions: 1. Check container logs: docker logs <container_id> 2. Verify environment variables 3. Check for port conflicts 4. Ensure sufficient system resources

CLI Issues

Issue: BFCLI commands not working

Symptoms: - Command not found errors - CLI crashes during execution

Solutions: 1. Verify global installation: npm list -g | grep bfcli 2. Reinstall CLI: npm install -g @bluefly/cli 3. Check for configuration issues 4. Verify environment variables

Logging and Debugging

Enabling Debug Logs

Set the DEBUG environment variable to enable detailed logging:

# For BFAPI
DEBUG=bfapi:* npm run dev

# For BFCLI
DEBUG=bfcli:* bfcli <command>

# For BFLLM
DEBUG=bfllm:* npm run dev

Checking Logs

# Docker logs
docker logs <container_id>

# Node.js application logs
cat logs/combined.log

# Error logs
cat logs/error.log

Using the Debug Endpoint

BFAPI provides a debug endpoint for troubleshooting (development only):

curl -X GET http://localhost:3000/debug/status

Getting Help

If you're unable to resolve an issue using this guide:

  1. Check GitLab issues for similar problems
  2. Contact the Bluefly support team
  3. Provide detailed information about the issue:
  4. Error messages and logs
  5. Steps to reproduce
  6. Environment details (OS, Node version, etc.)
  7. Configuration (sanitized of sensitive data)