How to Validate an Integration Config File

Use the validate command to check your integration configuration before running a sync. This helps catch configuration errors early, without requiring a full sync or Veza connection.

When to Use This Guide

Use this guide when you want to:

  • Verify your config.yaml is valid before running a sync

  • Debug configuration errors with clear, actionable error messages

  • Check that custom connection modules can be imported

  • Test database/API connectivity before a full sync

Prerequisites

  • OAA runner installed

  • An integration config file (config.yaml)

Validating Your Config

Basic Validation

Run the validate command without connectivity testing for quick feedback:

oaa app --config-file ./config.yaml validate

This also works with the short flag:

oaa app -c ./config.yaml validate

This validates:

  1. Config structure - Pydantic validation of the YAML file

  2. Connection modules - Verifies custom modules can be imported

  3. Preflight checks - Runs standard preflight checks

With Connectivity Testing

To also test actual connections to databases and APIs:

oaa app --config-file ./config.yaml validate --test_connectivity=True

This adds:

  1. Database connectivity - Tests DB connections (PostgreSQL, SQL Server, Oracle)

  2. File existence - Verifies CSV files exist

Understanding the Output

A successful validation looks like:

==================================================
STEP 1: Validating config structure...
==================================================
✅ Config structure is valid

==================================================
STEP 2: Validating connection modules...
==================================================
✅ Connection "my_api": module "my_integration.modules.api" imported successfully

==================================================
STEP 3: Running preflight checks...
==================================================
✅ check_configuration: passed
✅ check_sources: passed

==================================================
✅ VALIDATION PASSED - Configuration appears ready
==================================================

Common Validation Errors

Missing Required Field

If you see an error like:

  - app: Field required

This means the app section is required for custom_app runner type. Add it to your config:

version: v2
app:
  name: My Integration
  application_type: Custom App
sources:
  # ... your sources

Invalid Connection Type

❌ Connection "my_conn": could not find module "nonexistent_module"

This means the custom module specified in your connection doesn’t exist. Check:

  • The module name is correct

  • The module is in your modules/ directory or accessible via Python path

  • The module has a fetch() function

Invalid Source Configuration

  - sources.users.source_type: Input should be 'CSV', 'DB', 'API'...

This means the source_type value is invalid. Valid values include: csv, db, api, custom, csv_push, source.

Using with CI/CD

The validate command is useful in CI/CD pipelines to fail builds early:

#!/bin/bash
set -e

oaa app --config-file ./config.yaml validate

# Only proceeds to sync if validation passes
oaa app --config-file ./config.yaml run

Next Steps