Le but : retrouver vite la cause d'un problème. Chaque erreur ci-dessous a été rencontrée en vrai pendant les tests du kit (sauf mention), avec le message exact.
Où regarder d'abord :
source scripts/config.sh config/test.env
gcloud storage cat gs://$BUCKET/sync/last.json # dernière synchro
gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="'$SERVICE'" AND severity>=ERROR' \
--limit=20 --freshness=1h --format='value(textPayload)' # erreurs du service
gcloud logging read 'resource.type="cloud_run_job" AND resource.labels.job_name="'$SYNC_JOB'"' --limit=20 \
--format='value(textPayload)' # journaux de la synchro1. Déploiement
| Message | Cause | Solution |
|---|---|---|
Cloud Resource Manager API has not been used in project … before or it is disabled (Terraform, sur google_project_service) | Terraform a besoin de cette API pour activer les autres | gcloud services enable cloudresourcemanager.googleapis.com --project=$PROJECT_ID, puis relancer |
Publisher model is not allowed for use in Vertex RAG yet (création du corpus) | Modèle d'embeddings non accepté par RAG Engine (vu avec gemini-embedding-001) | Garder text-multilingual-embedding-002 (défaut) |
Construction d'image : 403 au 1er essai | Droits d'un compte de construction tout neuf pas encore actifs | Rien : le déploiement réessaie 4 fois à 40 s d'intervalle |
Après un 1er apply en échec : … is tainted, so must be replaced sur des API | Ressources marquées « à refaire » | Sans danger (disable_on_destroy = false) |
Le service reçoit CORPUS=4611686018427387904 | (corrigé dans le kit) name du corpus Terraform = numéro seul | Le kit utilise id (chemin complet) |
2. Interface et réponses
| Symptôme / message | Cause | Solution |
|---|---|---|
403 Forbidden dans le navigateur | Vous n'avez pas run.invoker sur le service | Ajouter votre compte à USERS puis apply |
L'interface s'affiche mais le chat ne répond pas ; navigateur : 403 sur /apps/assistant_documents/users/…/sessions | (corrigé dans le kit) ADK refuse une origine qui ne correspond pas à l'hôte : derrière le proxy, localhost:<port> ≠ …run.app | Le kit autorise localhost (ALLOW_ORIGINS) ; avec IAP ou un autre domaine, ajoutez-le à ALLOW_ORIGINS |
« La recherche dans les documents a échoué (RuntimeError) » ; journal : Permission 'discoveryengine.rankingConfigs.rank' denied | Compte du kit sans roles/discoveryengine.viewer (reranking). discoveryengine.user ne suffit pas (il ne contient pas cette permission, vérifié) | Inclus dans le kit ; si vous venez de l'ajouter : attendre la propagation IAM (jusqu'à 7 min) |
Réponse très lente puis Erreur 500 ; journal : 429 RESOURCE_EXHAUSTED | Quota partagé de Gemini saturé (fréquent sur un projet neuf) | L'agent réessaie 6 fois (2 à 30 s) ; si ça persiste : revenir au défaut gemini-2.5-flash / europe-west4, ou demander du débit provisionné (Provisioned Throughput) |
404 … Publisher model projects/…/locations/europe-west4/publishers/google/models/gemini-3.5-flash | Modèle indisponible dans la région | Gemini 3.5 : MODEL_LOCATION=global ; ou le défaut gemini-2.5-flash en europe-west4 |
| « Je ne trouve pas cette information » alors que le document existe | Pas encore indexé, ou mal lu | Vérifier qu'il est dans Documents indexés ; regarder le rapport (fichier en échec ?) ; PDF scanné : garder LAYOUT_PARSER=true |
| L'interface reste sur « Chargement… » | Proxy arrêté, ou service en cours de démarrage (1re requête ≈ 10 s) | Relancer bash scripts/ouvrir_interface.sh |
| « dépasse 30 Mo » | Limite de requête de Cloud Run (32 Mo) | Mettre le fichier dans le dossier Drive |
3. Synchro
| Symptôme / message | Cause | Solution |
|---|---|---|
À vérifier : « Drive « … » : N fichier(s) illisible(s) pour l'agent RAG (…). Partagez le dossier (lecteur) avec service-…@gcp-sa-vertex-rag… » (journal du job : 404 Unable to find some Google Drive resource(s)) | Agent de service RAG absent du partage du dossier (ou d'un fichier) | Ajouter l'adresse au partage du dossier (04) |
| « Drive « … » illisible (introuvable : plus partagé avec rag-kit-sa@…, ou supprimé) » | Le compte du kit ne voit plus le dossier. Cas vérifié : après destroy + apply, le compte recréé est une nouvelle identité pour Drive | Repartager avec rag-kit-sa@…, ou retirer le dossier. Rien n'est supprimé de l'index tant que ça dure |
403 … service-…@gcp-sa-vertex-rag… does not have storage.objects.create access | Agent RAG sans objectCreator sur le bucket (rapport d'import) | Inclus dans le kit ; vérifier gcloud storage buckets get-iam-policy gs://$BUCKET |
Journal du job : "statut": "occupe" répété | Deux passes en même temps (RAG Engine n'accepte qu'une opération par corpus) | Normal : la passe attend 15 s et recommence (15 min au plus) |
| Fichier compté « en échec » | Type non supporté (image, vidéo…), fichier protégé, trop gros | Détail : gcloud storage cat "gs://$BUCKET/sync/runs/*.ndjson" | grep -v '"Status": "OK"' |
| Synchro qui ne passe plus toute seule | Planification en pause ou en échec | gcloud scheduler jobs describe $SYNC_JOB --location=$REGION (état, dernier code) |
| Tout est réindexé à chaque passe | Réglage de parsing/découpage changé entre deux passes | Normal une fois après un changement ; sinon, vérifier que LAYOUT_PARSER est identique pour le service et le job |
4. Connexion Google (v2)
| Message | Cause | Solution |
|---|---|---|
| « Connexion Google pas encore configurée » | Pas de client OAuth dans le secret rag-kit-oauth-client | 04-bis, partie 2 |
Écran Google redirect_uri_mismatch | Interface ouverte sur un autre port que 8080, ou URI absente du client | bash scripts/ouvrir_interface.sh (port 8080) ; sinon ajouter l'URI dans le client OAuth |
Écran Google access_denied / « app non validée » bloquant | Compte absent des utilisateurs test (application Externe en test) | Ajouter le compte dans Google Auth Platform → Audience |
| « L'accès en lecture à Google Drive n'a pas été accordé » | Case Drive décochée sur l'écran Google | Se reconnecter et cocher l'accès Drive |
| Synchro : « Google Drive « … » : RefreshError … invalid_grant » | Jeton expiré (7 jours en mode test) ou accès retiré dans le compte Google | Se reconnecter ; pour éviter les 7 jours : publier l'application (04-bis, partie 5) |
Le sélecteur ne s'ouvre pas ; console du navigateur : API key not valid / origine refusée | Clé limitée à http://localhost:8080 | Ouvrir l'interface sur le port 8080, ou ajouter le référent à la clé rag-kit-picker |
Journal rag-kit-hook : 403 répétés | Notifications d'un ancien canal (source retirée, passe concurrente avant le verrou) : refusées, sans effet | Rien : le canal expire seul (7 jours au plus) |
| Fichier « non récupéré : … exportSizeLimitExceeded » | Google Doc/Slides de plus de 10 Mo à l'export | Le scinder, ou l'exporter en PDF dans Drive |
5. En local
| Message | Cause | Solution |
|---|---|---|
Request had insufficient authentication scopes (Drive) | Identifiants locaux sans le scope Drive | gcloud auth application-default login --scopes=…cloud-platform,…drive.readonly (05) |
FutureWarning: You are using a non-supported Python version (3.10…) | Python trop ancien pour les bibliothèques Google | Python 3.12 (comme l'image) |
vertexai.rag module is deprecated | Avertissement : ADK 2.10 impose google-cloud-aiplatform < 2 | Sans conséquence ; migrera vers agentplatform avec ADK |