gb validate

Validate Genbox configuration files.

Synopsis


gb validate [options]

Description

Checks your configuration for errors, warnings, and potential issues before creating environments. Validates schema, $detect resolution, connections, and environment references.

Options

Option	Description
`--profile <name>`	Validate with specific profile
`--strict`	Treat warnings as errors
`--fix`	Attempt to fix simple issues

Examples

Basic Validation


gb validate

With Profile


gb validate --profile full-stack

Strict Mode


gb validate --strict

Validation Output

Successful Validation


Validating configuration...

Schema validation:
  ✓ Version 4.0 valid
  ✓ Project structure valid
  ✓ All required fields present

$detect resolution:
  ✓ apps.web.port → 3000
  ✓ apps.web.framework → nextjs
  ✓ apps.api.port → 3050

Connection validation:
  ✓ web → api (NEXT_PUBLIC_API_URL)
  ✓ api → mongodb (MONGODB_URI)
  ✓ api → redis (REDIS_URL)

Environment references:
  ✓ staging.mongodb.url resolved
  ✓ staging.api.url resolved

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Result: ✓ Configuration valid

Ready to create environments!

Validation with Errors


Validating configuration...

Schema validation:
  ✓ Version 4.0 valid
  ✗ apps.admin.port: required field missing

$detect resolution:
  ✓ apps.web.port → 3000
  ✗ apps.admin.port: could not detect

    Tried: package.json scripts.dev (no --port flag found)

    Suggestions:
    • Add explicit value: port: 3001
    • Add --port flag to scripts.dev in admin/package.json
    • Check detected.yaml for available values

Connection validation:
  ✓ web → api (NEXT_PUBLIC_API_URL)
  ✗ api → elasticsearch: 'elasticsearch' not defined

    If api needs elasticsearch, add to provides:
    provides:
      elasticsearch:
        type: search
        image: elasticsearch:8
        port: 9200

Environment references:
  ⚠ staging.mongodb.url contains ${STAGING_MONGODB_URL}
    STAGING_MONGODB_URL not found in .env.genbox

    This will fail at runtime unless the variable is set.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Result: 2 errors, 1 warning

Fix errors before running 'gb create'.

Validation Categories

Schema Validation

Required fields present
Valid field types
Valid enum values
Proper structure

$detect Resolution

All markers can be resolved
Detected values available
No circular references

Connection Validation

Referenced services exist
Connection modes valid
No orphaned connections

Environment References

Environment variables exist
URLs properly formatted
Source environments defined

Fix Mode


gb validate --fix

Attempts to fix simple issues:

Add missing optional fields with defaults
Correct common typos
Format YAML properly

Notes

Run before gb create to catch issues early
Use --strict in CI/CD pipelines
Errors must be fixed; warnings are informational
--fix only handles simple issues