Troubleshooting

​

Installation & Authentication Issues

​

SDK Installation Fails

# Use Python 3.11+ environment
python --version  # Check version

# Create fresh virtual environment
python -m venv venv
source venv/bin/activate
pip install --upgrade pip

# Install from GitHub
pip install git+https://github.com/BudEcosystem/BudAIFoundry-SDK

​

Authentication Fails

# Logout and login again
bud auth logout
bud auth login

export BUD_API_KEY="your-api-key"

​

Pipeline Creation Issues

​

Pipeline Registration Fails

dag = p.to_dag()

# Bad - circular dependency
a = Action("a", type="log").after(b)
b = Action("b", type="log").after(a)  # Error!

# Good - linear dependency
a = Action("a", type="log")
b = Action("b", type="log").after(a)

python -m py_compile my_pipeline.py

​

Pipeline Execution Issues

​

Execution Fails Immediately

1. Check execution logs:
   bud execution logs exec_xyz789
   
2. Look for parameter errors:
   bud execution get exec_xyz789 | jq '.params'
   
3. Verify pipeline definition:
   bud pipeline get pipe_abc123
   

​

Template Resolution Errors

• Cannot resolve ${params.missing_param}
• Cannot resolve ${steps.nonexistent.output}

bud run pipe_abc123 --params '{"required_param": "value"}'

# Use correct action ID
process = Action("process_data", type="transform")
# Reference it correctly
next = Action("next", type="log").with_config(
    message="${steps.process_data.output}"  # Matches ID
)

# If output is {"data": {"value": 123}}
.with_config(value="${steps.previous.output.data.value}")

​

Action Timeout Errors

Action("train", type="ml_training") \
    .with_timeout(7200)  # 2 hours

​

Retry Exhaustion

execution = client.executions.get("exec_xyz789")
failed_action = next(a for a in execution.actions if a.status == "failed")

print(f"Attempts: {failed_action.attempt_count}")
print(f"Last error: {failed_action.error}")
print(f"All attempt errors:")
for i, attempt in enumerate(failed_action.attempts, 1):
    print(f"  Attempt {i}: {attempt.error}")

• If transient: Increase retry attempts
  .with_retry(max_attempts=5, delay=10)
  
• If permanent: Fix the underlying issue (wrong URL, invalid data, etc.)

​

Conditional Actions Never Execute

# Valid conditions
.when("${params.enabled} == true")
.when("${steps.eval.output.score} > 0.8")
.when("${params.env} == 'production'")

bud execution get exec_xyz789 | jq '.params'
bud execution get exec_xyz789 | jq '.actions[] | select(.name=="eval") | .output'

# Bad - comparing string to number
.when("${params.count} > 5")  # If count is "5" (string)

# Good - convert types
.when("int(${params.count}) > 5")

​

Performance Issues

​

Slow Pipeline Execution

1. Enable parallel execution:
   # These run concurrently
   task_a = Action("a", type="transform").after(start)
   task_b = Action("b", type="transform").after(start)
   task_c = Action("c", type="transform").after(start)
   
2. Reduce action timeouts:
   # Don't wait unnecessarily long
   api_call = Action("api", type="http_request").with_timeout(30)
   
3. Cache results:
   Action("fetch", type="http_request").with_config(
       cache_ttl=3600  # Cache for 1 hour
   )
   
4. Optimize data transfers:
   • Reduce data size passed between actions
   • Use references instead of copying large data
   • Compress data when possible

​

High Resource Usage

• Process data in batches
• Stream large datasets instead of loading all at once
• Use efficient data formats (Parquet instead of CSV)
• Configure resource limits per action

​

API & Network Issues

​

HTTP Request Actions Fail

Action("api", type="http_request").with_config(
    url="https://api.example.com/data",
    timeout=60,  # Increase timeout
    connect_timeout=10
).with_retry(max_attempts=3, delay=5)

# Include proper headers
.with_config(
    headers={
        "Authorization": "Bearer ${params.api_token}",
        "Content-Type": "application/json"
    }
)

.with_retry(
    max_attempts=5,
    delay=10,
    backoff=2.0  # Exponential backoff
)

​

Cannot Connect to Bud AI Foundry

1. Check network connectivity
2. Verify API endpoint:
   client = BudClient(base_url="https://api.budai.dev")
   
3. Check firewall settings
4. Verify SSL certificates

​

Data Issues

​

Data Validation Fails

log_data = Action("log_data", type="log").with_config(
    message="Data: ${steps.fetch.output}",
    level="debug"
)

.with_config(
    schema={
        "required_columns": ["id", "value"],
        "min_rows": 10,  # Lower threshold
        "max_missing_ratio": 0.2  # Allow more missing data
    }
)

​

Data Transformation Errors

# Add logging between transformations
step1 = Action("step1", type="transform").with_config(...)

log1 = Action("log1", type="log").with_config(
    message="After step1: ${steps.step1.output}",
    level="debug"
).after(step1)

step2 = Action("step2", type="transform").with_config(...).after(log1)

​

Getting Help

1. Check logs:
   bud execution logs exec_xyz789 --level error
   
2. Review execution details:
   bud execution get exec_xyz789
   
3. Search documentation:
   • Pipeline Concepts
   • Creating Pipelines
   • API Reference
4. Community support:
   • GitHub Issues
   • Community Forum
   • Discord
5. Contact support:
   • Email: support@bud.studio
   • Include: Pipeline ID, execution ID, error logs

​

Reporting Bugs

**Pipeline ID**: pipe_abc123
**Execution ID**: exec_xyz789
**Error Message**: [Full error text]
**Steps to Reproduce**:
1. Create pipeline with...
2. Execute with parameters...
3. Observe error at step...

**Expected Behavior**: [What should happen]
**Actual Behavior**: [What actually happens]

**Environment**:
- SDK Version: [version]
- Python Version: [version]
- OS: [OS and version]