Dépannage

Les problèmes les plus courants et comment les fixer. Parcourez la section qui matche votre symptôme.

Connexion + installation

« Permission denied » au premier login

Cause : l'email du bootstrap admin épinglé dans VITE_ADMIN_EMAIL ne matche pas l'email épinglé dans la fonction bootstrapAdminEmail() de vos règles Firestore.

Fix : mettez à jour les règles pour matcher — égalité de string exacte. Console Firestore → Rules → éditer → Publish.

Le SetupForm apparaît à chaque rechargement

Cause : le formulaire a uploadé config.js avec succès mais la prochaine requête tape une version cachée (sans les valeurs remplies) ou l'upload a silencieusement échoué.

Fix :

1. Hard-refresh (Cmd+Shift+R)
2. Si encore en échec, ouvrez https://<votre-site>/admin/config.js dans un onglet — devrait contenir window.__FLEXWEG_CONFIG__ = { /* values */ };. Si ça affiche null, l'upload n'a pas pris. Vérifiez le file manager Flexweg ; uploadez manuellement un fichier rempli si besoin.

Erreur de validation email Firebase

Cause : votre email admin n'est pas vérifié par Firebase. Les règles Firestore demandent email_verified == true pour le bootstrap admin.

Fix : Le formulaire d'installation déclenche automatiquement un sendEmailVerification. Vérifiez votre boîte mail, cliquez sur le lien Firebase, puis re-soumettez le formulaire.

En mode SQLite : « Master API key invalid »

Cause : votre clé API maître Flexweg est expirée ou révoquée.

Fix : générez une nouvelle clé permanente dans le tableau de bord Flexweg → Account → API. Re-soumettez le formulaire d'installation avec la nouvelle clé.

Publication

« Network error » au moment de publier

Cause : la connexion à l'API Files de Flexweg a coupé.

Fix : re-cliquez Publier. Le pipeline est idempotent — re-tenter ne crée pas de doublons.

Le post apparaît à la mauvaise URL (sans catégorie)

Cause : la catégorie a été créée juste avant la publication et n'était pas dans la snapshot ctx au moment du rendu.

Fix : utilisez Repair URLs dans le menu Regenerate — recalcule le chemin canonique pour chaque post en ligne et migre les fichiers qui ont dérivé.

Le HTML public ne s'update pas

Cause : cache navigateur ou cache CDN Flexweg.

Fix :

1. Hard-refresh côté visiteur (Cmd+Shift+R)
2. Si encore stale après plusieurs minutes : vérifiez que la publication a réussi (toast vert dans l'admin)
3. Vérifiez le fichier sur Flexweg via le file manager — si ancien : la publication a échoué silencieusement (rare)

Theme assets

Les changements de palette n'apparaissent pas

Cause : la CSS sur Flexweg n'a pas été re-uploadée après save.

Fix : cliquez Sync theme assets dans la page Thèmes. Hard-refresh côté visiteur.

Le menu / la recherche ne fonctionne pas

Cause : le script JS runtime du thème n'a pas été uploadé.

Fix : Sync theme assets. Vérifiez que /theme-assets/<id>-menu.js (ou -search.js) existe sur Flexweg.

Plugins externes

L'install échoue : « apiVersion out of range »

Cause : le plugin est compilé contre une API runtime trop ancienne ou trop récente.

Fix : demandez à l'auteur du plugin une version compatible. Ou mettez à jour votre admin si le plugin demande une API plus récente que celle déployée.

« Invalid hook call » à l'import du bundle

Cause : le bundle externe embarque sa propre instance de React au lieu d'utiliser celle de l'admin.

Fix : c'est un bug du plugin. L'auteur doit ajouter react aux external de son vite.config.ts. Voir Construire un bundle externe.

Le plugin disparaît après reload

Cause : le bundle crashe à l'import, l'admin attrape l'erreur silencieusement.

Fix : ouvrez la console navigateur, cherchez les erreurs [<plugin-id>] ou les erreurs de module loading. Désinstallez via la file manager Flexweg + l'entrée de settings/externalRegistry.

Multilang

Les pages FR ne reflètent pas les réglages de thème

Cause : un bug fixé dans flexweg-multilang v1.6.1+. Le themeConfig n'était pas passé dans la shadow ctx pour les rendus localisés.

Fix : upgradez flexweg-multilang à 1.6.1+.

Les boutons / sections custom du thème ne fonctionnent pas sur les pages FR

Cause : un bug fixé dans flexweg-multilang v1.5.2+. Le filtre post.html.body n'était pas appliqué dans renderLocalizedSingle.

Fix : upgradez flexweg-multilang à 1.5.2+.

/rss.xml est généré alors que la case est décochée

Cause : un bug fixé dans flexweg-rss qui ne nettoyait pas les fichiers stales si l'état précédent était déjà désactivé.

Fix : sauvegardez les réglages de flexweg-rss après upgrade — le nouveau cleanup nettoie le /rss.xml orphelin automatiquement.

Performance

L'admin rame au chargement initial

Cause : trop de posts en mode global (souscription live de toute la collection).

Fix : passez à paginationMode: "paginated" dans Réglages → Général → Performance. Configurez les index Firestore via le FirestoreSetupGate.

Les Regenerate prennent des heures

Cause : trop de posts + plugins coûteux + throttling de 75 ms entre uploads.

Fix :

• Désactivez temporairement les plugins coûteux pendant le bulk regen
• Ou regenerate par batches (catégorie par catégorie via Force regenerate du plugin)

Si rien de tout ça n'aide

• Ouvrez la console DevTools — cherchez les erreurs en rouge

• Vérifiez la console Firebase pour les errors côté base

• Vérifiez le tableau de bord Flexweg pour les errors côté hébergement

• Postez une issue sur le GitHub avec :

  • Version de l'admin (visible en bas de la sidebar)
  • Versions des plugins externes (page Plugins)
  • Le message d'erreur exact + capture d'écran
  • Étapes pour reproduire