# Purpose of fallback_base_url in Switchyard: Handling Unmatched HTTP Requests

> Learn the purpose of fallback_base_url in Switchyard for handling unmatched HTTP requests. Discover how this catch-all endpoint proxies requests when no route matches. Optimize your LLM routing.

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

---

**The `fallback_base_url` configuration parameter defines a catch‑all LLM endpoint that proxies HTTP requests when no configured route matches the incoming path, method, or model identifier.**

The `fallback_base_url` is an optional top‑level configuration field in the NVIDIA Switchyard routing engine that prevents hard failures for unqualified requests. When enabled, it references a client definition from the `[llm_clients]` table in the TOML configuration, allowing Switchyard to forward unmatched traffic to a default base URL rather than returning a 404 error. This mechanism ensures graceful degradation for edge‑case requests that fall outside defined routing rules.

## What Is the Purpose of fallback_base_url?

The primary purpose of **`fallback_base_url`** is to provide a safety net for HTTP requests that do not match any entry in Switchyard's routing table. Instead of terminating the connection with a "not found" error, Switchyard checks the `Runner` configuration for a designated fallback client.

According to the [[`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), this optional parameter names a specific client entry under the `[llm_clients]` table. The `base_url` defined in that client entry becomes the target for all unmatched requests, effectively creating a default gateway for traffic that would otherwise be rejected.

## How Unmatched HTTP Requests Are Handled

When an HTTP request hits the Switchyard server, the request handler first attempts to match it against configured routes. If no match is found, the implementation in [[`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs)](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs) executes the following logic:

1. Query the runner for the fallback URL via `state.runner.fallback_base_url()`.
2. If the method returns `Some(base_url)`, Switchyard constructs a proxied request preserving the original HTTP method, headers, and body, then forwards it to the fallback base URL.
3. If the method returns `None`, the server immediately returns a **404 Not Found** error indicating that no route matched and no fallback is configured.

The code specifically handles this branch:

```rust
// Located in crates/switchyard-server/src/lib.rs
let Some(base_url) = state.runner.fallback_base_url() else {
    return Err(Status::not_found("no route matched and no fallback configured"));
};
// Proxy the request to base_url...

```

The response from the fallback client—including status code, headers, and body—is then streamed back to the original caller transparently.

## Configuring the Fallback Client

To enable fallback behavior, define a client in the `[llm_clients]` section and reference it using the top‑level `fallback_client` key:

```toml

# config.toml

[llm_clients]
default = { base_url = "https://api.openai.com/v1" }

# Specifies which llm_clients entry to use as fallback

fallback_client = "default"

```

In this configuration, any request that does not match an explicit route will be forwarded to `https://api.openai.com/v1` with the original request path appended.

## Source Code Implementation Details

The fallback functionality is implemented across two primary crates:

- **[`crates/switchyard-runner/src/runner.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/runner.rs)**: Defines the `Runner` struct and its `fallback_base_url()` accessor method, which retrieves the configured fallback URL from the internal application state.
- **[`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs)**: Contains the HTTP server logic that invokes the fallback check when route resolution fails, handling the actual proxying of requests to the fallback base URL.

## Summary

- **`fallback_base_url`** provides a default destination for HTTP requests that do not match any configured Switchyard routes.
- The fallback client is defined in the `[llm_clients]` TOML table and referenced by the top‑level `fallback_client` configuration key.
- When enabled, unmatched requests are proxied to the fallback URL with original headers, methods, and bodies preserved.
- If no fallback is configured, Switchyard returns a **404 Not Found** error for unmatched requests.
- The logic is implemented in [`crates/switchyard-server/src/lib.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-server/src/lib.rs) using the `state.runner.fallback_base_url()` method defined in [`crates/switchyard-runner/src/runner.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/runner.rs).

## Frequently Asked Questions

### What happens if I do not configure a fallback_base_url?

If the `fallback_client` configuration is omitted or the referenced client does not exist, the `fallback_base_url()` method returns `None`. In this case, Switchyard returns a **404 Not Found** response for any request that does not match a defined route, preventing the request from reaching any backend LLM service.

### Does the fallback client preserve the original request headers and body?

Yes, when Switchyard proxies a request to the fallback base URL, it preserves the original HTTP method, headers, and request body. The server constructs a new outbound request to the fallback endpoint that mirrors the incoming request's content, ensuring compatibility with standard LLM API expectations.

### Can I configure different fallback clients for different deployment environments?

Yes, because `fallback_client` is a TOML configuration parameter, you can specify different fallback client names or base URLs in environment‑specific configuration files. Each deployment can reference a distinct entry in the `[llm_clients]` table, allowing staging and production environments to use separate default endpoints.

### How does fallback_base_url differ from standard route matching?

Standard route matching requires explicit configuration of paths, query parameters, or model identifiers to determine the target client. The **fallback_base_url** operates as a wildcard that only activates when all specific route checks fail, acting as a catch‑all rather than a precise routing rule.