Troubleshooting Guide¶

This guide covers common issues and their solutions when using ORB.

Configuration Issues¶

1. Configuration Not Found¶

Error Message:

ERROR: Configuration file not found
  No configuration found in:
    - /current/dir/config/config.json
    - ~/.config/orb/config.json
    - ~/.local/orb/config/config.json

Run 'orb init' to create configuration

Solution:

orb init

This creates the configuration directory and files needed for ORB to work.

2. Templates Not Found¶

Error Message:

ERROR: Templates file not found

Searched for:
  - awsprov_templates.json
  - templates.json

In directories:
  - ~/.config/orb/templates/
  - ~/.config/orb/

Run 'orb templates generate' to create example templates

Solution:

orb templates generate

This creates example templates you can customize for your environment.

3. AWS Credentials Missing¶

Error Message:

ERROR: AWS credentials not found

Profile: default
Region: us-east-1

Configure AWS credentials:
  aws configure --profile default

Or set environment variables:
  export AWS_ACCESS_KEY_ID=...
  export AWS_SECRET_ACCESS_KEY=...

Solution:

# Option 1: Use AWS CLI
aws configure

# Option 2: Use specific profile
aws configure --profile myprofile

# Option 3: Environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_DEFAULT_REGION=us-east-1

Configuration Locations¶

ORB looks for configuration in different locations depending on how it was installed:

Development Mode¶

/path/to/project/
├── config/
│   ├── config.json
│   └── templates/
└── work/

Virtual Environment Install¶

/path/to/project/
├── .venv/
├── config/              # Next to .venv
│   ├── config.json
│   └── templates/
└── work/

User Install (pip install --user)¶

~/.local/orb/
├── config/
│   ├── config.json
│   └── templates/
└── work/

System Install¶

/usr/local/orb/          # or /opt/orb/
├── config/
│   ├── config.json
│   └── templates/
└── work/

Platform-Specific Locations¶

Linux/Unix: - Config: ~/.config/orb/ - Data: ~/.local/share/orb/ - Cache: ~/.cache/orb/

macOS: - Config: ~/Library/Application Support/orb/config/ - Data: ~/Library/Application Support/orb/work/ - Cache: ~/Library/Caches/orb/

Windows: - Config: %APPDATA%\orb\ - Data: %LOCALAPPDATA%\orb\

Environment Variables¶

You can override default locations with environment variables:

# Override config directory
export ORB_CONFIG_DIR=/custom/path/config

# Override config file directly
export ORB_CONFIG_FILE=/custom/path/config.json

# Legacy HostFactory variables
export HF_PROVIDER_CONFDIR=/path/to/hostfactory/conf
export HF_PROVIDER_WORKDIR=/path/to/hostfactory/work

Validation Commands¶

Check Configuration¶

orb config show

Validate Setup¶

orb config validate

List Templates¶

orb templates list

Test AWS Connection¶

orb providers test aws

Common Solutions¶

Reset Configuration¶

# Remove existing config
rm -rf ~/.config/orb/

# Reinitialize
orb init

Force Reinitialize¶

orb init --force

Use Custom Config Location¶

orb --config /path/to/config.json templates list

Debug Mode¶

export ORB_LOG_LEVEL=DEBUG
orb templates list

Getting Help¶

If you're still having issues:

Check the logs in your work directory
Run with debug logging: ORB_LOG_LEVEL=DEBUG orb <command>
Validate your setup: orb config validate
Check the documentation: https://awslabs.github.io/open-resource-broker/
File an issue: https://github.com/awslabs/open-resource-broker/issues