Dati Binari in n8n: Guida Completa a File, Storage e Automazioni Sicure

Lavorare con immagini, PDF, ZIP e allegati è diventato quotidiano anche per chi fa marketing. Ecco perché conoscere i dati binari n8n è fondamentale: ti permette di ricevere file via Webhook, trasformarli, comprimerli, estrarre informazioni e inviarli dove servono (Drive, S3, FTP, email) in modo affidabile e scalabile. In questa guida pratica vedrai come funziona la struttura binaria degli item, come usare i nodi chiave (Convert to File, Extract from File, Read/Write Files from Disk), come scaricare e caricare file con HTTP Request e Webhook, e come manipolare buffer/base64 nel Code node. Inoltre, configurerai lo storage dei binari (memoria vs filesystem vs S3) tramite variabili d’ambiente, con best practice su performance, sicurezza e scaling. Alla fine avrai una checklist operativa, ricette end‑to‑end e un troubleshooting rapido per sbloccare gli errori più comuni, così da integrare i file binari su n8n nei tuoi flussi senza stress.

📚 Nuovo a n8n? Parti dalla guida completa: cos’è n8n e come funziona.

Concetti base e struttura degli item binari

Per ogni passaggio del workflow, n8n tratta i dati come una lista di “item”. Ogni item ha due sezioni:

json: i dati strutturati (campi, numeri, stringhe).
binary: i file binari su n8n associati a quell’item.

Struttura degli item binari: proprietà

data: contenuto in base64 (o riferimento esterno, a seconda della modalità di storage).
mimeType: tipo MIME (es. image/png, application/pdf).
fileName: nome del file (es. report.pdf).
fileExtension: estensione (es. pdf, png).
fileSize: dimensione in byte (se disponibile).

Differenza tra JSON e binario: quando convertire e perché

Resta in JSON quando ti servono campi leggibili e manipolazioni testuali.
Passa al binario quando lavori con file veri e propri, devi inviarli come allegati o salvarli su storage. Usa il nodo Convert to File di n8n per creare un file a partire da testo/base64, ed Extract from File n8n per ZIP/PDF quando vuoi estrarre contenuti e riconvertirli in JSON.

Referenziare i binari nelle espressioni

Nel nodo consumatore indica la “binary property” che contiene il file (es. file). Assicurati che il nome sia coerente tra i nodi.
Se rinomini la proprietà (es. da data a file), aggiorna tutti i nodi a valle che usano quel file.

Passaggio tra nodi e debugging

Errore tipico: “binary property not found”. Controlla il nome della proprietà, ispeziona l’item in esecuzione e verifica che il nodo precedente produca davvero item.binary..

Lettura, scrittura e conversione: i nodi core per i file

Read/Write Files from Disk

Per installazioni aggiornate, usa Read/Write Files from Disk per leggere/scrivere dal filesystem. È l’evoluzione dei nodi Read Binary File/Write Binary File.
Tipico uso: leggere un PDF da una cartella condivisa per poi inviarlo via email; oppure salvare su disco file generati a runtime.

Convert to File | Extract from File

Convert to File: prende in input testo/Base64 e genera un file binario con nome ed estensione corretti. Esempio: trasformare il contenuto HTML in un .html o un CSV stringa in .csv.
Extract from File: prende in input un file binario e lo converte in JSON, o estrae file contenuti (per ZIP/PDF quando previsto), così puoi analizzarne il contenuto con nodi HTML/XML o trasformarlo.

Esempio Convert to File (config essenziale)

{
  "name": "Convert to File",
  "type": "n8n-nodes-base.convertToFile",
  "typeVersion": 1,
  "parameters": {
    "operation": "textToFile",
    "textInputField": "={{$json.report_markdown}}",
    "outputFieldName": "file",
    "fileName": "monthly-report.md",
    "mimeType": "text/markdown"
  }
}

Esempio Extract from File (estrazione testo da PDF/ZIP, flusso generico)

{
  "name": "Extract from File",
  "type": "n8n-nodes-base.extractFromFile",
  "typeVersion": 1,
  "parameters": {
    "binaryPropertyName": "file",
    "operation": "auto",
    "outputFieldName": "extracted"
  }
}

Lettura/Scrittura e trigger

Local File Trigger e monitoraggio directory: utile per reagire a nuovi file in arrivo.
FTP/SFTP per trasferimento file in n8n: scarica/carica file su server remoti come parte del flusso.

HTTP, Webhook ed Email: integrazione file in entrata/uscita

HTTP Request con payload binario in n8n (download)

Imposta “Response format: File” e “Binary Property” (es. file) per scaricare immagini, PDF, audio.

Esempio:

{
  "name": "Download File",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 1,
  "parameters": {
    "url": "https://example.com/files/{{$json.id}}.pdf",
    "method": "GET",
    "responseFormat": "file",
    "binaryPropertyName": "file"
  }
}

HTTP Request (upload)

Usa form-data e imposta la proprietà binaria come file da caricare. Indica la “Binary Property” e il campo form.

{
  "name": "Upload File",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 1,
  "parameters": {
    "url": "https://api.example.com/upload",
    "method": "POST",
    "sendBody": true,
    "contentType": "multipart-form-data",
    "bodyParametersUi": {
      "parameter": [
        {
          "name": "file",
          "value": "={{$binary.file}}",
          "type": "formBinary"
        }
      ]
    }
  }
}

Upload file con Webhook n8n

Il Webhook riceve multipart/form-data e inserisce gli allegati in item.binary con il nome del campo usato nel form (es. upload). A valle puoi salvare o trasformare questi file.

Gestione allegati email in n8n

I nodi email (es. Gmail/IMAP) possono esporre gli allegati in binary. Filtra i messaggi, estrai l’allegato e inoltralo (Drive/S3/FTP) o processalo (Extract from File).

Manipolazioni con Code: base64, buffer e metadati file

Il Code node è perfetto per operazioni su buffer/base64 e per impostare mimeType e fileName.

Creare un file binario da stringa

// Crea file .txt a partire da una stringa
const content = ($json.text || 'Hello n8n!');
const data = Buffer.from(content, 'utf8').toString('base64');
return [
  {
    json: $json,
    binary: {
      file: {
        data,
        mimeType: 'text/plain',
        fileName: 'message.txt',
        fileExtension: 'txt'
      }
    }
  }
];

Leggere base64 da un binario e salvarlo in JSON

const b = $binary.file;
const base64 = b.data; // attenzione: può essere un riferimento se usi storage esterno
return [{ json: { ...$json, file_base64: base64, mimeType: b.mimeType, fileName: b.fileName } }];

Rinominare la binary property

const b = $binary.file;
return [{ json: $json, binary: { attachment: b } }];

Impostare mimeType e nome file in n8n

Quando generi il binario (Convert to File/Code), valorizza sempre mimeType e fileName: semplifica invii HTTP/email e salvataggi su storage.

Storage dei binari: memoria vs filesystem vs S3 e variabili d’ambiente

Modalità disponibili e trade‑off

Memoria (default): semplice, ma non adatta a file grandi e a cluster.
Filesystem: salva sotto una directory locale; ottimo per file medi e per ridurre RAM. Richiede volumi condivisi tra worker in cluster.
Storage esterno (S3/compatibile): ideale per carichi/cluster; centralizza e scala, con costi e latenza da valutare.

Variabili d’ambiente per lo storage dei file in n8n

N8NAVAILABLEBINARYDATAMODES: elenco delle modalità disponibili (es. filesystem).
N8NBINARYDATASTORAGEPATH: percorso dove n8n salva i file (default: N8NUSERFOLDER/binaryData).
N8NDEFAULTBINARYDATAMODE: default mantiene i binari in memoria (“default”). Imposta “filesystem” per file su disco.
NODES_EXCLUDE: per escludere nodi che leggono/scrivono binari (hardening).

Esempio (bash)

export N8N_AVAILABLE_BINARY_DATA_MODES=filesystem
export N8N_BINARY_DATA_STORAGE_PATH=/home/node/.n8n/binaryData
export N8N_DEFAULT_BINARY_DATA_MODE=filesystem

Cambio modalità e pruning

La pulizia (pruning) agisce sulla modalità attiva. Se hai salvato in S3 e poi passi a filesystem, la pulizia riguarderà solo i file su filesystem. Pianifica eventuali migrazioni/bonifiche.

Sicurezza

Usa varianti _FILE per gestire segreti via file/Secrets.
Limita permessi sulla cartella binaria; definisci retention e job di pruning.

Performance, costi e scaling: linee guida pratiche

Limiti e performance

Evita file enormi in memoria; preferisci filesystem o storage esterno.
Comprimi prima di inviare/archiviare (compressione e archiviazione ZIP in n8n) per ridurre banda e storage.

Scaling e HA

Con filesystem: monta volumi condivisi tra worker e nodi main/worker in queue mode per coerenza dei riferimenti.
Con S3: semplifica il cluster eliminando il vincolo dei volumi condivisi; considera latenza e costi.

Ridurre peso e costi

Cancella file temporanei dopo l’uso (pruning e pulizia dei file temporanei in n8n).
Scegli formati efficienti (CSV per tabelle, WebP per immagini quando possibile).

Privacy e governance

Se i file contengono PII, definisci retention policy e access control. Evita di replicare file sensibili in troppi step.

Ricette end‑to‑end

Ricevere upload via Webhook, validarlo e salvarlo

Webhook (POST multipart/form-data): riceve il file in binary.upload.
If: controlla mimeType/estensione consentiti.
Write Files from Disk: salva su path organizzati per data/cliente.
HTTP Request (facoltativo): invia metadati a un CRM/DB.

Scaricare immagine, creare ZIP e inviare via Email

HTTP Request (Response format: File, binaryPropertyName=file).
Compression: aggiungi file a un archivio .zip (binary property zip).
Email: allega il binario zip e invia al team.

Estrarre contenuti da ZIP e produrre CSV

Extract from File (binaryPropertyName=file): ottieni lista di file interni in JSON.
Code: parse e normalizza dati.
Convert to File: genera CSV (textToFile) in binary.csv.
HTTP Response/Webhook Reply: restituisci il CSV scaricabile.

Troubleshooting rapido

“binary property not found”: verifica il nome della binary property nel nodo consumatore; controlla che il nodo precedente la produca davvero (ispeziona l’item).
mimeType mancante/errato: imposta esplicitamente mimeType (Convert to File/Code) per evitare problemi con upload/email.
Percorsi errati su disco: conferma N8NBINARYDATASTORAGEPATH e permessi; in cluster usa volumi condivisi.
Time‑out di rete in upload/download: riduci dimensioni (compressione), aumenta time‑out del nodo HTTP, usa retry/backoff.
File enormi in memoria: passa a N8NDEFAULTBINARYDATAMODE=filesystem o adotta storage esterno.

Quick Takeaways

Pianifica la binary property e mantienila coerente tra i nodi per evitare errori di referenza.
Usa Convert to File ed Extract from File per passare tra JSON e binario in modo sicuro e ripetibile.
Per download/upload imposta HTTP Request su “Response format: File” e usa multipart/form-data per gli upload.
Gestisci storage con N8NDEFAULTBINARYDATAMODE e N8NBINARYDATASTORAGEPATH; filesystem o S3 per produzione/scaling.
Riduci costi e rischi: comprimi, cancella temporanei, applica retention e permessi stretti.
In cluster, condividi i volumi (filesystem) o adotta storage esterno per evitare inconsistenze.

Conclusione

Portare file e allegati nei tuoi workflow amplia enormemente ciò che puoi automatizzare: dal ricevere asset via form alla generazione di report, fino a compressione, trasformazione e invio multi‑canale. Conoscere i dati binari n8n significa padroneggiare la struttura json/binary degli item, i nodi chiave per leggere/scrivere/convertire e le integrazioni HTTP/Webhook/Email. La configurazione corretta dello storage (memoria vs filesystem vs S3) tramite variabili d’ambiente rende i flussi più stabili, scalabili e sicuri, mentre le buone pratiche su performance, pruning e governance evitano costi e incidenti. Il modo migliore per iniziare? Scegli un caso d’uso concreto (upload via Webhook o download + ZIP + email), imposta la binary property, testa il flusso e passa gradualmente a storage persistente in produzione. In poco tempo porterai più file “nel circuito” delle tue automazioni, liberando tempo a te e al tuo team per attività a maggior valore.

FAQ

Come rappresento un file in un item n8n?

Un file vive in item.binary. con campi come data (base64 o riferimento), mimeType, fileName, fileExtension, fileSize. Mantieni coerente il nome della proprietà tra i nodi.

Come passo da testo a file e viceversa?

Usa il nodo Convert to File di n8n per generare un file (es. CSV/MD) da testo o base64; usa Extract from File n8n per ZIP/PDF quando vuoi estrarre contenuti e convertirli in JSON.

Come scaricare e caricare file via HTTP?

Per scaricare imposta HTTP Request con “Response format: File” e scegli la “Binary Property”. Per caricare usa multipart/form-data specificando la proprietà binaria come file.

Come configuro lo storage per grandi file?

Imposta N8NDEFAULTBINARYDATAMODE=filesystem e definisci N8NBINARYDATASTORAGEPATH. Valuta storage esterno (S3/compatibile) per cluster/HA. Ricorda che la pulizia (pruning) agisce sulla modalità attiva.

Come evito l’errore “binary property not found”?

Assicurati che il nodo produttore crei davvero item.binary. e che il consumatore usi lo stesso nome. Ispeziona l’item in esecuzione e aggiungi controlli If/Code per validare presenza e mimeType.

Ci dai una mano?

Quale flusso creerai per primo: upload via Webhook con salvataggio su storage o estrazione ZIP→CSV con invio email? Condividilo e invita il tuo team: costruiamo insieme automazioni che trattano i file in modo semplice e sicuro!