How to Validate TOML Deployment Configuration with `switchyard-server --dry-run`

Use switchyard-server --config <file>.toml --dry-run to validate a TOML deployment configuration without starting the HTTP listener—exits with status 0 on success or prints errors and exits non-zero on failure.

Switchyard is NVIDIA's open-source Rust proxy for serving LLM traffic. Before deploying to production, you need to verify that your routing configuration is syntactically correct and schema-compliant. The switchyard-server binary provides a dry-run mode that performs full validation without binding to any network sockets, making it safe for CI pipelines and local development workflows.

What --dry-run Validates

When you invoke switchyard-server with the --dry-run flag, the binary executes a three-step validation sequence defined in crates/switchyard-server/src/main.rs:

1. Parses the TOML file using the internal toml crate to catch syntax errors.
2. Validates the schema against the official TOML schema reference, which defines required sections such as [routes], [targets], and routing-algorithm parameters.
3. Prints configuration errors (missing fields, malformed values, type mismatches) and exits without starting the HTTP listener.

Because no socket is opened, you can run this command in restricted environments or automated pipelines without security concerns.

Basic Validation Command

Run the following to validate your deployment configuration:

switchyard-server --config routes.toml --dry-run

The command produces either:

• Success: Silent exit with status code 0 (or "Configuration OK" message with --verbose)
• Failure: Detailed error messages and non-zero exit status

This pattern is documented in the README Quick-Start section and the Getting Started guide.

CI Pipeline Integration

Add validation to your GitHub Actions workflow to catch misconfigurations before deployment:

- name: Validate Switchyard config
  run: |
    switchyard-server --config routes.toml --dry-run
  env:
    # No secrets required for validation

Since the validator does not start the server, no RUST_LOG configuration or endpoint credentials are needed.

Verbose Output for Debugging

To inspect resolved configuration values—including defaults injected by the server—combine --dry-run with --verbose:

switchyard-server --config routes.toml --dry-run --verbose

This displays the fully resolved configuration structure, helping you identify where default values override your explicit settings.

TOML Schema Requirements

The validator enforces the schema defined in [docs/reference/toml_schema.md](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/reference/toml_schema.md#L10-L14). A minimal valid configuration includes:

• [routes] section defining path patterns and target mappings
• [targets] section specifying backend endpoints
• Routing algorithm parameters (e.g., algorithm = "round_robin")

Common validation failures include:

• Missing required fields in [routes] or [targets]
• Invalid IP addresses or port numbers in target definitions
• Unknown routing algorithm names
• Type mismatches (e.g., string where integer expected)

Key Source Files

File	Purpose
crates/switchyard-server/src/main.rs	CLI parsing, TOML validation, and conditional server startup based on --dry-run flag
docs/reference/toml_schema.md	Canonical schema definition used by the validator
README.md	Quick-start examples showing --dry-run usage
docs/getting_started.md	Step-by-step validation workflow

Summary

• switchyard-server --config <file>.toml --dry-run validates TOML deployment configurations without network side effects.
• Exit status 0 confirms validity; non-zero status with error messages indicates configuration problems.
• Use --verbose to inspect resolved configuration with defaults.
• Safe for CI pipelines—no secrets or network permissions required.
• Validation logic resides in crates/switchyard-server/src/main.rs and follows the schema in docs/reference/toml_schema.md.

Frequently Asked Questions

Does --dry-run check network connectivity to targets?

No. The --dry-run flag only validates the TOML file syntax and schema compliance. It does not attempt to connect to target endpoints or verify that backend services are reachable. Use health-check endpoints or separate integration tests for connectivity validation.

Can I validate multiple TOML files in one command?

No. Each invocation of switchyard-server processes a single configuration file via --config <path>. To validate multiple files, run the command separately for each or create a shell loop:

for f in configs/*.toml; do
  switchyard-server --config "$f" --dry-run || exit 1
done

What exit codes does --dry-run return?

Exit code 0 indicates successful validation. Non-zero codes indicate failure: typically 1 for general errors, with specific codes for parse failures (toml crate errors) or schema violations. The error message printed to stderr describes the specific failure.

Is --dry-run available in all Switchyard versions?

The --dry-run flag is available in the current stable release as documented in the README and Getting Started guide. If your binary lacks this flag, upgrade to the latest version from the NVIDIA-NeMo/Switchyard repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}