Skip to main content

Error Codes Reference

Error Codes Reference

Common error codes and solutions across the LLM platform.

Agent Errors

AGT-001: Agent Initialization Failed

Cause: Agent failed to initialize properly.

Solution:

# Check manifest
buildkit ossa validate .agents/<agent>/manifest.json

# Verify dependencies
buildkit agents check-deps <agent-id>

# Restart agent
buildkit agents restart <agent-id>

AGT-002: Task Execution Timeout

Cause: Task exceeded maximum execution time.

Solution:

# Increase timeout in manifest
# .agents/<agent>/manifest.json
{
  "execution": {
    "timeout": 300000  // 5 minutes
  }
}

AGT-003: OSSA Protocol Violation

Cause: Agent not compliant with OSSA specification.

Solution:

# Validate compliance
buildkit ossa validate .agents/<agent>/manifest.json

# Fix violations and redeploy
buildkit agents deploy <agent-id>

LLM Errors

LLM-001: API Rate Limit Exceeded

Cause: Too many API requests.

Solution:

# Check rate limits in Phoenix
open http://localhost:6006

# Implement backoff
# Add to agent config
{
  "llm": {
    "rateLimit": {
      "maxRequests": 50,
      "perMinute": 1
    }
  }
}

LLM-002: Invalid API Key

Cause: Missing or invalid API key.

Solution:

# Check token
cat ~/.tokens/anthropic

# Set token
echo "your-api-key" > ~/.tokens/anthropic
chmod 600 ~/.tokens/anthropic

LLM-003: Context Length Exceeded

Cause: Prompt too long for model.

Solution:

  • Reduce prompt length
  • Use Claude Opus (200k context)
  • Implement chunking strategy

Database Errors

DB-001: Connection Failed

Cause: Cannot connect to database.

Solution:

# Check PostgreSQL status
docker ps | grep postgres

# Test connection
psql -h localhost -U postgres -d llm_platform

# Verify environment variables
echo $DATABASE_URL

DB-002: Migration Failed

Cause: Database migration error.

Solution:

# Check migration status
npm run migrate:status

# Rollback and retry
npm run migrate:rollback
npm run migrate:up

Network Errors

NET-001: Service Unreachable

Cause: Cannot connect to service.

Solution: See Connection Issues

NET-002: DNS Resolution Failed

Cause: Cannot resolve hostname.

Solution: See Connection Issues

Kubernetes Errors

K8S-001: Pod OOMKilled

Cause: Pod exceeded memory limit.

Solution: See Kubernetes Troubleshooting

K8S-002: Image Pull Error

Cause: Cannot pull container image.

Solution:

# Check image exists
docker pull <image>

# Check registry credentials
kubectl get secret regcred -n agents -o yaml

# Create secret if missing
kubectl create secret docker-registry regcred \
  --docker-server=<registry> \
  --docker-username=<user> \
  --docker-password=<token> \
  -n agents

Testing Errors

TEST-001: TDD Compliance Failed

Cause: Tests don't meet TDD requirements.

Solution: See TDD Enforcement

TEST-002: Coverage Below Threshold

Cause: Code coverage < 80%.

Solution: See Coverage Requirements

Getting Help

Check Logs

# Agent logs
buildkit agents logs <agent-id>

# Service logs
docker logs <service>

# Kubernetes logs
kubectl logs -n <namespace> <pod>

View Traces

# Phoenix
open http://localhost:6006

# Jaeger
open http://localhost:16686

Report Issues

Create issue: https://gitlab.com/blueflyio/agent-platform/documentation/-/issues

Related Pages