nas-runbooks/common/bifrost-vk-incidents.md

# Bifrost — Incidents VK & fallback (consolidé)

**Date** : 2026-07-09 (fusionne BIFROST-VK-OPENCODE-FIX.md 23/06 + bifrost-vk-stale-cache-et-fallback-opencode.md 06/07)
**Tags** : infra, bifrost, vk, opencode, openrouter, cout
Guide d'accès général : common/bifrost-access.md.

## Règles durables (à retenir avant tout debug)

1. Auth Bifrost = header `x-bf-vk`, JAMAIS `Authorization: Bearer` → 401.
2. Bifrost ne hot-reload NI les clés provider NI le VK store → **restart du container = premier réflexe** sur tout `401 virtual_key_not_found` inexpliqué (cache VK désynchronisé de la DB).
3. config.json chargé au boot = source providers ; `allow_all_keys=1` en DB ; ne pas dupliquer providers entre config.json et le store ; l'UI peut re-casser ces réglages.
4. Fallbacks Hermes → **opencode-go** (forfait), plus jamais openrouter (facturation réelle à chaque échec du modèle primaire).
5. Auditer périodiquement les règles de routing : le NOM d'une règle peut ne pas correspondre à sa cible réelle en base (désync vue sur la règle Haiku).
6. Portainer : l'ID container change après recreate → toujours le re-résoudre avant stop/start.
7. n8n PUT /workflows : payload strict {name, nodes, connections, settings} → 400 sinon.

## Incident 23/06/2026 — « Résumé indisponible » veille bolbol.tn

- `could not auto resolve a provider` : la VK Nabil-Key (bfk-e5832bfe…) n'avait pas OpenCode dans `governance_virtual_key_provider_configs` → deepseek-v4-flash introuvable. Fix : INSERT provider opencode (weight 1.0, allowed_models deepseek-v4-flash/pro, glm-5.1, kimi-k2.6, allow_all_keys=1) + clé persistée dans `config_keys` + restart bifrost.
- `GoUsageLimitError` : job cron hermes-nyora orchestrateur avec model/provider null → OpenCode direct, quota hebdo épuisé. Fix : jobs.json → model openrouter/deepseek-v4-flash pour l'orchestrateur ; workflow n8n 9378593adccf42dc → retry gemini-2.5-flash sur GoUsageLimitError.
- Architecture VK Nabil-Key finale : openrouter (modèles :free), google (gemma-4, gemini-2.5-flash/lite), nvidia_nim, opencode (deepseek-v4-flash/pro, glm-5.1, kimi-k2.6).

## Incident 06/07/2026 — VK stale-cache + fallbacks payants

1. 401 `virtual_key_not_found` répétés sur « VEILLE | Ingest Opportunités » alors que la VK était exacte en base → cache VK désynchronisé, **un simple restart bifrost a suffi**.
2. hermes-nyora (pilote mimo-v2.5) a basculé 2× sur son fallback natif openrouter (bypass Bifrost, coût réel facturé) → les 3 config.yaml migrés vers fallback `opencode-go/deepseek-v4-flash`, `key_env: OPENCODE_GO_API_KEY` (nom réel du compose top-level, PAS OPENCODE_API_KEY). Restart des 3 agents (les appels restart API peuvent timeout côté client → vérifier l'état, ne pas re-tenter en boucle ; start manuel parfois requis).
3. Règle routing « Haiku → Gemini 2.5 Flash » pointait en réalité vers openrouter/deepseek-v4-flash payant → `routing_targets` corrigé vers google/gemini-2.5-flash. Backups config.db pris avant chaque édit.

## Pilote mimo-v2.5 (contexte)

Bilan J+1 (06/07) : 389 appels, 0,5% d'échec (réponse vide = reasoning épuisant max_tokens) → fix `model.max_tokens: 8192` sur hermes-nyora. **Verdict final 08/07 : GARDER mimo, V4 Flash en fallback** — détails : hermes-nyora/verdict-pilote-mimo-v25.md.

## Vérification type

```bash
curl -X POST http://bifrost:8080/v1/chat/completions -H 'x-bf-vk: <Nabil-Key>' \
  -d '{"model":"deepseek-v4-flash","max_tokens":30,"messages":[{"role":"user","content":"dis OK"}]}'
# 200 + routing_info.provider=opencode attendu
```


## Incident 11/07/2026 — VK stale-cache (3e occurrence) + modele manquant dans bifrost-proxy

**Contexte** : config Hermes Desktop sur le poste de Yesmine, via bifrost-proxy (port 3086).

1. **401 virtual_key_not_found recurrent sur la vk Yesmine**, alors que la vk est active et correctement provisionnee en base (providers openrouter/google/nvidia_nim/opencode, allow_all_keys=1 sur les 4). Confirme dans logs.db : rafales d'echecs 401 entrecoupees d'appels reussis sur la meme vk, meme minute — meme signature que l'incident du 06/07 (cache VK memoire desynchronise de la DB). **Fix identique : restart du conteneur bifrost.** Troisieme occurrence en 5 jours -> ce n'est plus un incident isole, cf. section "A surveiller" plus bas.
2. **`opencode/deepseek-v4-flash` absent du picker du client** alors qu'autorise sur la vk cote Bifrost. Cause : le catalogue statique `/mnt/docker/bifrost-proxy/models.json` (servi par nginx sur `/v1/models`, independant de Bifrost) avait perdu cette entree lors de la reduction de stack fin juin/debut juillet (l'ancien fichier plus complet contenait `deepseek/deepseek-v4-flash`, la refonte l'a droppee au passage a la nomenclature `opencode/*`). Fix : entree reajoutee dans models.json (`opencode/deepseek-v4-flash`, ctx 128000), backup de l'ancien fichier garde (`models.json.bak-20260711-manual`). Aucun restart necessaire, le fichier est relu a chaque requete `/v1/models`.
3. Un vrai `HTTP 500 provider API error` a egalement ete observe en parallele, mais sans rapport avec les deux points ci-dessus : erreur `INTERNAL` renvoyee directement par Google AI Studio sur `gemma-4-26b-a4b-it` (panne ponctuelle fournisseur, confirmee sur `google-key1` et `google-key2`). Aucune action cote infra.

**Recette client complete (Hermes Desktop, MacBook inclus)** : voir `common/bifrost-access.md`, section "Recette Hermes Desktop" (MAJ 11/07) — port 3086, `Authorization: Bearer <vk bfk-*>`, catalogue statique a completer manuellement si un modele manque.

## A surveiller (mis a jour 11/07)

Le cache VK stale n'est plus un incident isole : 3 occurrences en 5 jours (23/06 racine differente, 06/07, 11/07) avec le meme symptome et le meme fix (restart bifrost). A investiguer en profondeur si ca continue : pourquoi le cache memoire ne s'invalide pas sur ecriture DB (write recent sur config.db sans invalidation cache observe le 11/07). En attendant, reflexe standard confirme : **tout 401 virtual_key_not_found inexplique -> restart bifrost avant toute autre investigation**, ne pas re-tester en boucle sur le meme cache fige.