# 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.

## Incident 02/09/2026 — modeles bloques sur redaction-pro malgre cle provider correcte

**Contexte** : redaction-pro (VK dediee `vk-redaction-pro`) — presque tous les modeles demandes par Nabil (ox-alpha-free, x-previex-f-free, laguna-s-2.1-free, nemotron-3-*-free, muse-spark-1.2-contributor(-free)) renvoyaient 403 `model_blocked`.

**Cause confirmee** : deux couches de whitelist independantes, il faut les deux pour qu'un appel passe :
1. `config_keys.models_json` — whitelist au niveau de la cle provider brute (ex. id=8 `opencode-1`), partagee par TOUS les consommateurs de cette cle (Hermes inclus).
2. `governance_virtual_key_provider_configs.allowed_models` — whitelist specifique a CHAQUE VK (ex. id=72 pour vk-redaction-pro / opencode). C'est cette couche qui bloquait le plus souvent, meme quand la cle provider autorisait deja le modele.

**Piege supplementaire confirme (revalide 4e fois)** : editer ces deux colonnes JSON en DB (sqlite direct, colonnes `models_json` / `allowed_models`) **ne prend PAS effet a chaud** — `docker restart bifrost` obligatoire, cf. "A surveiller" ci-dessus (meme famille que le cache VK stale).

**Verification finale des noms de modeles** : avant d'ajouter un modele a la whitelist, verifier qu'il existe reellement via `GET https://opencode.ai/zen/go/v1/models` (Authorization Bearer <cle opencode-go>) — plusieurs noms fournis par Nabil (ox-alpha-free, x-previex-f-free, laguna-s-2.1-free, nemotron-3-ultra-free, nemotron-3.5-lightning-free) n'existaient PAS dans ce catalogue cote `opencode-go` (Zen REST, celui de Bifrost) alors qu'ils existent bien cote `opencode` natif (OAuth device-flow, utilise par Hermes via Telegram) ou cote OpenRouter sous un nom different (vendor/modele:free) — voir common/opencode-go-migration.md pour le detail de cette dualite de catalogues.

**Resultat** : whitelist nettoyee (retrait des 6 IDs fantomes/deprecies), `hy3` ajoute et confirme fonctionnel (~2-6s, gratuit), `mimo-v2.5` confirme fonctionnel pour redaction-pro (~40-45s, deja whiteliste par ailleurs).

**Backup pris avant toute modification** : `config.db.bak-redaction-pro-models-20260902-163248`.

## Suite 03/09/2026 — clé Groq réellement manquante depuis 01/07, jamais posée

Le commit `f52b2b5` du 01/07 titré "fix: Groq provider Bifrost (cle manquante)" n'a en réalité RIEN corrigé côté Bifrost — seuls des chips morts (Gemma GAS, doublon OR) ont été retirés de `index.html`, les 4 chips Groq (dont 2 avec des noms de modèles déjà décommissionnés côté Groq) sont restés en place. Vérifié le 03/09 : `config_keys` ne contenait AUCUNE ligne pour `provider_id=82` (groq) — provider enregistré dans `config_providers` mais jamais de clé associée. Deux mois d'indisponibilité silencieuse.

**Fix definitif** : clé Groq récupérée depuis l'environnement d'un conteneur `hermes-agent-*` (`docker exec <container> env | grep GROQ_API_KEY` — la clé est injectée aux 3 instances Hermes via `docker-compose.yml` top-level, `${HERMES_*_GROQ_KEY}`), testée en direct sur `api.groq.com` avant d'être ajoutée. INSERT dans `config_keys` (provider_id=82) + `governance_virtual_key_provider_configs` (allow_all_keys=1) pour la VK redaction-pro. Restart bifrost obligatoire (même piège que d'habitude).

**Modèles Groq réellement valides sur ce compte** (vérifié via `GET https://api.groq.com/openai/v1/models`) : `openai/gpt-oss-120b` et `openai/gpt-oss-20b` uniquement — ultra-rapides (~0.15-0.3s). `llama-3.3-70b-versatile` et `meta-llama/llama-4-scout-17b-16e-instruct` (les deux autres chips historiques de redaction-pro) **n'existent plus du tout** dans le catalogue Groq — décommissionnés côté fournisseur, pas un problème de config. Retirés de `index.html`.

**Leçon** : un titre de commit "fix: X (cause identifiée)" ne garantit pas que X a été corrigé — toujours vérifier le diff réel, pas juste le message. Ici le diagnostic était juste mais l'action corrective a été oubliée en route.