Troubleshooting

Common issues and solutions for Bud AI Foundry Pipelines

This guide covers common problems you may encounter when working with pipelines and provides solutions to resolve them quickly.

Installation & Authentication Issues

SDK Installation Fails

Problem: pip install fails with dependency errors

Solutions:

# 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

Problem: bud auth login doesn’t work or shows errors

Solutions:

Browser doesn't open

Manually copy the URL from the terminal and open it in your browser.

Token expired

# Logout and login again
bud auth logout
bud auth login

Use API key instead

export BUD_API_KEY="your-api-key"

Get your API key from the dashboard.

Pipeline Creation Issues

Pipeline Registration Fails

Problem: bud pipeline create returns validation errors

Common Causes & Solutions:

Missing dag export

Error: “Pipeline file must export ‘dag’ variable”

Solution: Ensure your file ends with:

dag = p.to_dag()

Invalid action type

Error: “Unknown action type: xyz”

Solution: Use valid action types: log, transform, http_request, ml_training, ml_inference, set_output, conditional, parallel

Circular dependency

Error: “Circular dependency detected”

Solution: Remove circular references in .after() chains:

# 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)

Syntax errors in pipeline file

Error: “SyntaxError in pipeline definition”

Solution: Validate Python syntax:

python -m py_compile my_pipeline.py

Pipeline Execution Issues

Execution Fails Immediately

Problem: Pipeline fails right after starting

Debugging Steps:

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

Problem: Action fails with “Cannot resolve template variable”

Error Examples:

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

Solutions:

Missing parameter

Cause: Parameter wasn’t provided during execution

Solution: Include all required parameters:

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

Wrong step reference

Cause: Referenced step doesn’t exist or hasn’t executed yet

Solution: Check action IDs match:

# 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
)

Accessing nested output

Cause: Incorrect path to nested output field

Solution: Use correct JSON path:

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

Action Timeout Errors

Problem: Action status shows “timeout”

Solutions:

Increase timeout

For legitimately long-running tasks:

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

Optimize the action

• Reduce data size
• Use more efficient algorithms
• Enable caching
• Consider splitting into smaller actions

Check for hanging processes

Look for infinite loops or blocking operations in custom action code.

Retry Exhaustion

Problem: Action fails after all retry attempts

Debugging:

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}")

Solutions:

• 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

Problem: Action with .when() is always skipped

Solutions:

Check condition syntax

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

Verify condition values

Check what values are being compared:

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

Type mismatches

Ensure types match:

# 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

Problem: Pipeline takes much longer than expected

Optimization Strategies:

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

Problem: Pipeline consumes excessive memory or CPU

Solutions:

• 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

Problem: http_request actions fail with network errors

Common Causes:

Connection timeout

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)

Authentication errors

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

Rate limiting

Add delays and retries:

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

Cannot Connect to Bud AI Foundry

Problem: SDK cannot reach Bud AI Foundry API

Solutions:

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

Problem: validate_schema action fails

Solutions:

Check actual data format

Log the data first to see what you’re receiving:

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

Adjust schema requirements

Be flexible with validation rules:

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

Data Transformation Errors

Problem: Transform actions produce unexpected results

Debugging:

# 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

If you can’t resolve an issue:

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: [e-mail]
   • Include: Pipeline ID, execution ID, error logs

Reporting Bugs

When reporting a bug, include:

**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]

Pipeline Concepts

Learn fundamental concepts

Quick Start

Get started with pipelines

API Reference

Complete API documentation

GitHub

View source code and examples