Common Issues

This guide covers the most frequently encountered issues when working with Teabar and their solutions.

Environment Creation Issues

Environment Fails to Create

Symptoms:

• teabar env create hangs or times out
• Error: “Failed to create environment”

Solutions:

1. Check quota limits:

teabar quota show

If you’ve reached your environment limit, delete unused environments:

teabar env list --status idle
teabar env delete idle-env-1 idle-env-2

2. Verify blueprint exists:

teabar blueprint list
teabar blueprint validate my-blueprint

3. Check for resource availability:

teabar status --resources

4. Review detailed error:

teabar env create my-env --verbose 2>&1 | tee create.log

Environment Stuck in “Creating” State

Symptoms:

• Environment status shows “creating” for more than 10 minutes

Solutions:

# Check creation progress
teabar env status my-env --verbose

# View creation logs
teabar logs my-env --phase create

# Force recreate if stuck
teabar env delete my-env --force
teabar env create my-env

Connection Issues

Cannot Connect to Environment

Symptoms:

• teabar connect fails
• SSH connection refused
• “Connection timed out” errors

Solutions:

# Verify environment is running
teabar env status my-env

# Check if environment has a public endpoint
teabar env info my-env --endpoints

# Test connectivity
teabar env ping my-env

# Regenerate connection credentials
teabar env connect my-env --regenerate

Intermittent Connection Drops

Symptoms:

• Connections work sometimes but randomly fail
• SSH sessions disconnect unexpectedly

Solutions:

# Enable connection keepalive
teabar config set connection.keepalive 60

# Check environment health
teabar health my-env

# View connection logs
teabar logs my-env --component network

Performance Issues

Environment Running Slowly

Symptoms:

• High response times
• Applications unresponsive
• Commands take long to execute

Solutions:

1. Check resource usage:

teabar metrics show my-env

2. Identify resource constraints:

# CPU throttling
teabar metrics show my-env --metric cpu_throttle

# Memory pressure
teabar metrics show my-env --metric memory_pressure

# Disk I/O wait
teabar metrics show my-env --metric io_wait

3. Scale up resources:

teabar env resize my-env --cpu 4 --memory 8G

4. Check for noisy neighbors (shared infrastructure):

teabar env migrate my-env --reason performance

High Memory Usage

Symptoms:

• OOM (Out of Memory) kills
• Application crashes with memory errors

Solutions:

# View memory breakdown
teabar metrics show my-env --metric memory_breakdown

# Identify memory-hungry processes
teabar exec my-env -- ps aux --sort=-%mem | head -20

# Increase memory limit
teabar env resize my-env --memory 16G

# Enable memory alerts
teabar alerts create --env my-env --metric memory_percent --threshold 80

Database Issues

Database Connection Refused

Symptoms:

• “Connection refused” when connecting to database
• Application can’t reach database

Solutions:

# Check database component status
teabar env status my-env --component database

# Verify database is running
teabar exec my-env --component database -- pg_isready

# Check database logs
teabar logs my-env --component database --tail 100

# Restart database component
teabar env restart my-env --component database

Database Out of Disk Space

Symptoms:

• “No space left on device” errors
• Database becomes read-only

Solutions:

# Check disk usage
teabar metrics show my-env --component database --metric disk_usage

# Expand storage
teabar env resize my-env --component database --storage 50G

# Clean up old data
teabar exec my-env --component database -- vacuumdb --all --analyze

Deployment Issues

Deployment Fails

Symptoms:

• teabar deploy returns error
• Environment doesn’t update after deploy

Solutions:

# Check deployment status
teabar deploy status

# View deployment logs
teabar deploy logs --verbose

# Rollback to previous version
teabar deploy rollback

# Redeploy with verbose output
teabar deploy --verbose 2>&1 | tee deploy.log

Image Pull Errors

Symptoms:

• “Failed to pull image” errors
• “Image not found” errors

Solutions:

# Verify image exists
docker manifest inspect myregistry.com/myapp:tag

# Check registry credentials
teabar config get registry.credentials

# Update registry credentials
teabar config set registry.credentials.myregistry "$(cat ~/.docker/config.json)"

# Use a different tag
teabar env update my-env --image myapp:latest

CLI Issues

CLI Commands Hang

Symptoms:

• Commands don’t return
• No output from CLI

Solutions:

# Check CLI version
teabar version

# Update CLI
teabar update

# Clear CLI cache
teabar cache clear

# Run with debug output
TEABAR_DEBUG=1 teabar env list

Authentication Errors

Symptoms:

• “Unauthorized” errors
• “Token expired” messages

Solutions:

# Check auth status
teabar auth status

# Re-login
teabar auth login

# Clear stored credentials
teabar auth logout
teabar auth login

# Test authentication
teabar auth test

Blueprint Issues

Blueprint Validation Fails

Symptoms:

• teabar blueprint validate returns errors
• Environment creation fails with blueprint errors

Solutions:

# Validate with detailed output
teabar blueprint validate my-blueprint --verbose

# Check blueprint syntax
teabar blueprint lint teabar.yaml

# View blueprint schema
teabar blueprint schema

Common validation errors:

Blueprint Changes Not Applied

Symptoms:

• Updated blueprint but environment unchanged

Solutions:

# Force blueprint sync
teabar env sync my-env --force

# Recreate environment
teabar env delete my-env
teabar env create my-env

# Check blueprint version
teabar blueprint version my-blueprint

Log Issues

Logs Not Appearing

Symptoms:

• teabar logs returns empty
• Missing log entries

Solutions:

# Check if logging is enabled
teabar config get logging.enabled

# Check log retention
teabar config get logging.retention

# Verify component name
teabar env status my-env --components

# Check all components
teabar logs my-env --all-components

Quick Diagnostic Commands

Run these commands to gather diagnostic information:

# Full environment diagnostic
teabar diagnose my-env

# Generate support bundle
teabar support bundle my-env --output diagnostic.zip

# Check system status
teabar status --all

Getting More Help

If these solutions don’t resolve your issue:

1. Search existing issues: Check the Teabar GitHub issues
2. Check status page: Visit status.teabar.dev for service status
3. Contact support: See the Support page
4. Debug mode: Run commands with TEABAR_DEBUG=1 for verbose output