Constraints and Caveats

• Turn-scoped fallback: Each new user message starts with the primary model restored. Within a single turn, fallback activates at most once. If fallback also fails, normal error handling takes over (retries, then error message).
• Prompt cache reset: Fallback resets the prompt cache. The next request re-reads the entire history at full input-token price, losing the ~75-90% cached rate discount. When the turn ends and primary is restored, the first request back on primary is also a full re-read (unless primary's cache TTL hasn't expired). Long sessions bouncing between providers can cost noticeably more than staying put.
• No environment variables for the primary fallback chain: Configure exclusively through config.yaml or hermes fallback.
• Config shape: fallback_providers (plural, list) is the current config shape; fallback_model (singular) is legacy. When both are set, fallback_providers takes priority. Running hermes fallback writes the current fallback_providers key and migrates legacy config on write.
• Entry validation: Entries in fallback_providers missing either provider or model are ignored.
• Provider main: NOT a valid value for top-level model.provider — only for auxiliary tasks.
• Auxiliary task fallback triggers: For auxiliary tasks with an explicit provider, only capacity errors (HTTP 402, 429 daily-quota, connection failure) trigger fallback. Transient HTTP 429 rate limits respect the explicit provider choice and do NOT trigger the fallback ladder.
• base_url precedence: For auxiliary tasks, base_url takes precedence over provider.
• API key handling: Hermes does NOT reuse OPENROUTER_API_KEY for custom endpoints. It uses the configured api_key or falls back to OPENAI_API_KEY.
• Compression graceful degradation: If no provider is available for compression, Hermes drops middle conversation turns without generating a summary. This does not fail the session.
• Subagent inheritance: Subagents inherit the parent agent's primary fallback chain.
• Cron job inheritance: Cron jobs inherit the configured fallback_providers chain (or legacy fallback_model) when they create an agent.
• Legacy config migration: Legacy configs with compression.summary_model / compression.summary_provider / compression.summary_base_url are automatically migrated to auxiliary.compression.* on first load (config version 17).

Failure Modes

• If fallback also fails within a turn, normal error handling takes over (retries, then error message).
• If every layer of auxiliary fallback fails, Hermes logs Auxiliary <task>: ... all fallbacks exhausted at WARNING level and re-raises the original error.
• If a provider returns a different phrase for daily-quota exhaustion and Hermes does not trigger fallback, that is a bug. Open an issue with the exact error string.
• If no provider is available for compression, Hermes drops middle conversation turns without generating a summary (graceful degradation).

Examples

OpenRouter as Fallback for Anthropic Native

model:
  provider: anthropic
  default: claude-sonnet-4-6
fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

Nous Portal as Fallback for OpenRouter

model:
  provider: openrouter
  default: anthropic/claude-opus-4
fallback_providers:
  - provider: nous
    model: nous-hermes-3

Local Model as Fallback for Cloud

fallback_providers:
  - provider: custom
    model: llama-3.1-70b
    base_url: http://localhost:8000/v1
    key_env: LOCAL_API_KEY

Codex OAuth as Fallback

fallback_providers:
  - provider: openai-codex
    model: gpt-5.3-codex

Auxiliary Task Fallback Detail

Auxiliary tasks (vision, web extract, compression, skills hub, MCP, approval, title generation, triage specifier) each have their own fallback behavior. When an auxiliary task is configured with an explicit provider, only capacity errors (HTTP 402, 429 daily-quota, connection failure) trigger the fallback ladder. Transient HTTP 429 rate limits do not trigger fallback for tasks with an explicit provider.

The fallback_chain parameter under an auxiliary task overrides the main fallback_providers chain for that specific task. Each entry in fallback_chain can include a timeout value in seconds, which overrides the task-level timeout for that specific fallback candidate.

If base_url is set for an auxiliary task, it takes precedence over the provider setting, allowing direct endpoint override without provider resolution.

Delegation Fallback

Subagents spawned by delegate_task inherit the parent agent's primary fallback chain. You can override the provider and model for all subagents by configuring the delegation: section in config.yaml. Optionally, you can set base_url and api_key for a direct endpoint override.

Cron Job Fallback

Cron jobs inherit the configured fallback_providers chain (or legacy fallback_model) when they create an agent. You can override the provider and model for a specific cron job by setting provider and model parameters in the cron job definition.

Cache and Cost Implications

Fallback resets the prompt cache. The next request after a fallback re-reads the entire conversation history at full input-token price, losing the approximately 75-90% cached rate discount. When the turn ends and the primary model is restored, the first request back on primary is also a full re-read unless the primary's cache TTL has not expired. Long sessions that bounce between providers can cost noticeably more than staying with a single provider.

Legacy Configuration

The fallback_model parameter is a legacy single fallback key. It is still honored for backward compatibility, but fallback_providers takes priority when both are set. Running hermes fallback writes the current fallback_providers key and migrates legacy config on write.

Legacy configs with compression.summary_model, compression.summary_provider, and compression.summary_base_url are automatically migrated to auxiliary.compression.* on first load (config version 17).

Troubleshooting

• If fallback does not activate when expected, check that the error matches the trigger conditions listed in "When Fallback Activates".
• If a custom endpoint fallback fails, verify that base_url points to a running OpenAI-compatible endpoint and that key_env references an environment variable that is set.
• If auxiliary task fallback does not trigger for daily-quota exhaustion, check the exact error string from the provider. If it is a different phrase, open an issue.
• If compression fails and no provider is available, Hermes drops middle conversation turns without generating a summary. This is graceful degradation and does not fail the session.
• If you see Auxiliary <task>: ... all fallbacks exhausted at WARNING level, all fallback layers for that auxiliary task have been exhausted. The original error is re-raised.