n8n fichiers binaires : guide technique 2026

Un workflow n8n qui plante avec le message « No binary data found » figure parmi les frustrations les plus courantes des utilisateurs. La raison tient souvent à une mauvaise compréhension de la façon dont n8n, l’outil d’automatisation open source, traite les fichiers : images, PDF, feuilles de calcul ou documents circulent dans les workflows sous une forme bien distincte des données JSON textuelles. Cette distinction conditionne le choix des nœuds, la configuration du stockage et même la performance d’une instance auto-hébergée.

Comprendre les données binaires dans n8n

Ce que recouvre un fichier binaire

Dans n8n, les données binaires désignent tout contenu non textuel : un PDF téléchargé via une API, une image envoyée par un webhook, un fichier Excel récupéré sur un Google Drive. Contrairement aux objets JSON manipulés couramment, ces fichiers ne sont pas lisibles directement dans l’interface : ils apparaissent sous l’onglet « Binary » de la sortie d’un nœud, avec leurs métadonnées (nom, type MIME, taille).

Quand un fichier entre dans un workflow, n8n le sauvegarde dans le stockage de l’instance et crée une référence — appelée binary data reference — attachée à l’item JSON correspondant. Cette mécanique permet de transporter plusieurs fichiers à travers un workflow sans saturer la mémoire, à condition de configurer le stockage correctement.

La structure d’un item binaire

Chaque item dans n8n peut contenir deux compartiments : un objet json et un objet binary. L’objet binaire est lui-même indexé par un nom de propriété, généralement data par défaut, mais qui peut être renommé. Sous ce nom se trouvent le contenu encodé, le mimeType, le fileName et la taille du fichier.

Cette structure explique pourquoi un nœud peut « perdre » un fichier en chemin : si l’item suivant ne préserve pas la propriété binaire, ou si le nom attendu en entrée diffère du nom réel, le fichier devient inaccessible alors qu’il existe toujours physiquement dans le stockage.

JSON et binaire : deux flux parallèles

Le malentendu le plus fréquent consiste à confondre la présence d’une URL ou d’un nom de fichier dans le JSON avec la présence du fichier lui-même. Une chaîne de caractères https://exemple.com/document.pdf dans le JSON n’est qu’une référence textuelle ; tant qu’un nœud HTTP Request configuré en mode « File » ou « Download » n’a pas téléchargé le contenu, aucun binaire n’existe dans l’item.

Nœuds natifs pour lire, écrire et convertir des fichiers

Read/Write Files from Disk

Ce nœud lit ou écrit des fichiers directement sur le système hôte. Il fonctionne uniquement sur les instances auto-hébergées, puisque le cloud n8n ne donne pas accès au système de fichiers. On l’utilise typiquement pour traiter des fichiers déposés dans un dossier surveillé ou pour exporter des rapports générés dans un workflow.

Extract From File pour parser PDF, CSV et Excel

Le nœud Extract From File convertit un fichier binaire en JSON structuré. Il prend en entrée un PDF, un CSV, un fichier Excel ou un document texte, et restitue son contenu sous forme exploitable par les nœuds suivants. Pour un tableur, chaque ligne devient un item JSON distinct, ce qui facilite les itérations.

Le nœud Spreadsheet File, plus ancien mais toujours disponible, joue un rôle similaire pour les fichiers .xls et .xlsx et reste utile lorsqu’on a besoin d’un contrôle fin sur le parsing.

Convert to File pour générer des fichiers en sortie

L’opération inverse passe par Convert to File. À partir d’une liste d’items JSON, ce nœud génère un CSV, un Excel, un HTML, un JSON exporté ou un fichier texte. La sortie est un binaire prêt à être envoyé par mail, déposé sur un FTP ou uploadé vers un stockage cloud.

HTTP Request en mode binaire

Pour télécharger un fichier depuis une URL, le nœud HTTP Request dispose d’une option « Response Format » à régler sur « File ». Le contenu de la réponse est alors stocké dans la propriété binaire de l’item au lieu d’être interprété comme du JSON ou du texte. À l’inverse, pour uploader un fichier via une API REST, l’option « Send Binary File » permet d’attacher le binaire au corps de la requête, généralement en multipart/form-data.

Manipuler les données binaires avec le nœud Code

Lire et modifier les métadonnées

Le nœud Code donne un accès programmatique aux binaires via this.helpers.getBinaryDataBuffer(). La méthode retourne un Buffer Node.js exploitable avec n’importe quelle bibliothèque standard. On peut ainsi renommer un fichier, modifier son type MIME ou inspecter les premiers octets pour détecter un format réel.

Encoder et décoder en base64

Certaines APIs exigent que les fichiers soient transmis en base64 dans le corps JSON d’une requête. En JavaScript, la conversion s’effectue avec buffer.toString('base64') dans un nœud Code. Le chemin inverse — décoder une chaîne base64 reçue d’une API pour la transformer en fichier exploitable — passe par Buffer.from(chaine, 'base64') puis this.helpers.prepareBinaryData(), qui enregistre le résultat comme un binaire reconnu par n8n.

Passer des binaires entre nœuds avec $binary

La variable $binary permet de référencer la propriété binaire d’un item courant à l’intérieur d’expressions ou de code. Pour accéder à un binaire issu d’un nœud précédent nommé « HTTP Request », on utilise $('HTTP Request').item.binary.data. Cette syntaxe sert notamment à reconstruire un item qui aurait perdu sa partie binaire en route.

Conserver les binaires dans Edit Fields (Set)

Par défaut, le nœud Edit Fields, anciennement appelé Set, ne propage pas les données binaires. L’option « Include Other Fields » ou le mode « Keep Only Set » détermine ce comportement. Pour conserver un fichier à travers un Set, il faut activer explicitement le passage des binaires dans les options du nœud, sous peine de voir la propriété disparaître à la sortie.

Configurer le stockage des binaires en auto-hébergement

Mémoire ou filesystem

n8n propose deux modes de stockage pour les binaires : memory, qui conserve les fichiers en RAM le temps de l’exécution, et filesystem, qui les écrit sur disque. Le mode mémoire est rapide mais sature vite si plusieurs workflows manipulent simultanément des fichiers volumineux. Le mode filesystem soulage la RAM au prix d’un peu d’I/O disque.

Variables d’environnement

Le choix s’opère via la variable N8N_DEFAULT_BINARY_DATA_MODE, qui accepte les valeurs memory, filesystem ou s3. Pour le mode filesystem, N8N_BINARY_DATA_TTL définit la durée de rétention des fichiers temporaires, ce qui évite de saturer le disque sur une instance qui traite beaucoup d’exécutions. La documentation officielle sur la gestion des données binaires détaille l’ensemble des paramètres applicables.

Stockage S3 pour les fichiers volumineux

Depuis la version 1.5, n8n peut déléguer le stockage des binaires à un bucket S3 ou compatible (MinIO, Cloudflare R2). Cette configuration devient indispensable dès lors qu’une instance traite régulièrement des fichiers de plusieurs centaines de mégaoctets, ou qu’elle tourne en mode queue avec plusieurs workers : le S3 partagé garantit qu’un worker peut accéder à un binaire écrit par un autre.

Erreurs fréquentes et leurs causes

« No binary data found »

Ce message signale qu’un nœud attend un binaire en entrée mais ne le trouve pas. Trois causes dominent : le nœud précédent n’a pas généré de binaire (oubli du mode « File » sur HTTP Request), un nœud intermédiaire a supprimé la propriété, ou le nom de la propriété binaire ne correspond pas à celui configuré dans le nœud cible.

Perte des binaires après un Edit Fields

Comme évoqué, le nœud Edit Fields filtre par défaut les binaires. La correction consiste à ouvrir les options du nœud et à activer l’inclusion des champs binaires, ou à passer en mode « Include All Fields ».

Mauvais nom de propriété binaire

Chaque nœud qui consomme un binaire dispose d’un champ « Input Binary Field » à renseigner. La valeur par défaut data ne convient pas si le nœud source a produit un binaire sous un autre nom. Vérifier le nom exact sous l’onglet Binary de la sortie précédente règle la majorité des cas.

Transmettre un fichier à un sous-workflow

Lorsqu’on appelle un sous-workflow via le nœud Execute Workflow, les binaires ne sont pas transmis automatiquement de la même manière que le JSON. Il faut s’assurer que le mode « Run Once for Each Item » est cohérent et que le nœud Trigger du sous-workflow accepte les propriétés binaires. Dans certaines configurations, encoder le fichier en base64 dans le JSON puis le redécoder côté sous-workflow reste la méthode la plus fiable.

FAQ sur la manipulation des fichiers binaires dans n8n

Comment accéder aux données binaires d’un nœud précédent

Via la syntaxe $('NomDuNoeud').item.binary.nomDuChamp dans une expression, ou via this.helpers.getBinaryDataBuffer(itemIndex, nomDuChamp) dans un nœud Code. Le nom du champ se lit sous l’onglet Binary de la sortie du nœud source.

Comment convertir un fichier binaire en base64

Le plus simple passe par un nœud Code avec const buffer = await this.helpers.getBinaryDataBuffer(0, 'data'); const base64 = buffer.toString('base64');. Le résultat peut ensuite être injecté dans un champ JSON.

Pourquoi les fichiers binaires ne sont-ils pas chargés

Trois pistes : le nœud source n’est pas configuré pour produire un binaire (HTTP Request en mode JSON au lieu de File), le stockage de l’instance est plein, ou le TTL des binaires temporaires a expiré entre deux exécutions manuelles.

Comment passer un fichier binaire entre deux workflows

Pour deux workflows liés par Execute Workflow, transmettre le binaire dans l’item passé en paramètre fonctionne dans la majorité des cas. Pour deux workflows totalement indépendants, l’option robuste consiste à uploader le fichier sur un stockage externe (S3, Drive, FTP) depuis le premier, puis à le télécharger depuis le second. Pour découvrir des exemples de workflows couvrant ce type de cas, plusieurs ressources documentent des architectures éprouvées.

Quelle différence entre Extract From File et Convert to File

Extract From File transforme un fichier binaire en JSON exploitable (lecture d’un CSV, parsing d’un PDF). Convert to File fait l’inverse : il génère un fichier binaire à partir d’une liste d’items JSON. Les deux nœuds sont symétriques et couvrent la majorité des conversions courantes.

Comment obtenir une URL publique pour un fichier

n8n ne fournit pas nativement d’URL publique pour un binaire. La méthode standard consiste à uploader le fichier vers un service externe (S3 avec ACL publique, Google Drive avec lien partagé, Cloudinary, Bunny.net) via le nœud dédié, puis à récupérer l’URL retournée par l’API. La communauté n8n recense de nombreux templates couvrant ce cas précis.

Avant de déployer un workflow qui manipule des fichiers en production, vérifier la configuration du stockage binaire (mode et TTL) et tester avec un fichier représentatif du volume réel évite la grande majorité des incidents. Un workflow validé sur un PDF de 100 Ko peut se comporter très différemment avec un Excel de 50 Mo.