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

> Validate TOML deployment configuration using switchyard-server --dry-run. Check your config for errors before deployment without starting the server.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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:

```bash
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](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/README.md#L85-L89) and the [Getting Started guide](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/getting_started.md#L172-L176).

## CI Pipeline Integration

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

```yaml
- 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`:

```bash
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)](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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/main.rs) | CLI parsing, TOML validation, and conditional server startup based on `--dry-run` flag |
| [`docs/reference/toml_schema.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/reference/toml_schema.md) | Canonical schema definition used by the validator |
| [`README.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/README.md) | Quick-start examples showing `--dry-run` usage |
| [`docs/getting_started.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/main.rs) and follows the schema in [`docs/reference/toml_schema.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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:

```bash
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](https://github.com/NVIDIA-NeMo/Switchyard) repository.