Convert File To Base64 - Synthreo Builder

---

Purpose

The ConvertFileToBase64 node converts binary files (such as images, PDFs, or other file formats) into Base64-encoded strings.

This is necessary when preparing files for APIs, JSON payloads, or database fields that only accept text-based data. The node reads the file from a specified path, encodes its contents, and outputs the resulting string as a new field in the workflow data - optionally alongside file metadata such as name, size, and MIME type.

---

Parameters

Data Source

Name	Type	Required	Default	Description
File Path Expression	Text (dynamic)	Required	Empty	Path to the field in the incoming data that contains the file location or reference. Supports dynamic expressions referencing upstream node output, such as upload.file_path or a static file path like /storage/reports/report.pdf.

Processing

Name	Type	Required	Default	Description
Read File	Toggle (On/Off)	Optional	On	When enabled, the node reads the file from the resolved path and encodes its binary contents. Disable only if the file reference is already in a pre-read binary format from a previous node.
Include Metadata	Toggle (On/Off)	Optional	Off	When enabled, the output includes additional fields describing the file, such as file name, size in bytes, and MIME type. Useful when the receiving system or downstream node requires file details alongside the encoded content.

Output

Name	Type	Required	Default	Description
Option	Dropdown	Optional	Original with appended result column	Controls how the output record is structured. Original with appended result column retains all incoming fields and adds the Base64 string as a new column. Return result column only outputs only the Base64 string field, discarding the original input fields.
Result Property Name	Text	Optional	"base64_result"	The name of the output column that holds the Base64-encoded string.

---

How It Works

When the node executes, it resolves the file path from the field identified by File Path Expression. If Read File is enabled, the node reads the binary content of the file at that path and encodes it using standard Base64 encoding. If Include Metadata is enabled, additional descriptive fields are added to the record. The encoded string (and optional metadata) is placed into the column named by Result Property Name, and the full record is passed to the next node according to the selected Option.

Base64 encoding increases data size by approximately 33% compared to the original binary file. This is a known characteristic of the encoding format and should be factored into performance planning for large files.

---

Example Usage

API Integration with Image Upload

A workflow processes user-uploaded images and submits them to an external OCR API that requires Base64-encoded input.

Configuration:

• File Path Expression: upload.file_path
• Read File: On
• Include Metadata: On
• Option: Original with appended result column
• Result Property Name: encoded_image

Outcome: The file is read, encoded as a Base64 string, and attached as a new field in the workflow output alongside the original upload record and file metadata. The encoded string is ready for inclusion in a JSON API request body.

PDF Submission to Document Management System

A workflow receives invoice files and must submit them to a document management API that accepts Base64-encoded PDFs.

Configuration:

• File Path Expression: invoice.storage_path
• Read File: On
• Include Metadata: Off
• Option: Return result column only
• Result Property Name: encoded_pdf

Outcome: Only the Base64 string is passed downstream, ready to be inserted directly into an API request payload.

---

Best Practices

• File size awareness: Base64 encoding increases data size by approximately 33%. Avoid encoding very large files (such as high-resolution video or large archive files) unless necessary, as this increases memory usage and network payload size.
• Validation before encoding: Confirm that the file exists and is readable at the resolved path before this node executes. An upstream file existence check can prevent encoding errors caused by missing or inaccessible files.
• Security: Sanitize and validate file path expressions to prevent unauthorized access to files outside intended directories. Do not allow user-supplied input to directly control the file path without validation.
• Caching: If the same file is encoded multiple times within a workflow run or across repeated workflow executions, consider caching the encoded string upstream to avoid redundant I/O operations.
• Consistency: When pairing this node with ConvertBase64ToFile (for round-trip encode/decode workflows), use the same file type assumptions on both ends to maintain format integrity.
• Metadata usage: Enable Include Metadata when the receiving system or downstream node needs to know the file name, size, or MIME type alongside the encoded content. Disable it when only the raw Base64 string is needed to keep the output lean.

---

Troubleshooting

Output is empty or Base64 string is missing

Check that the File Path Expression resolves to a non-empty, valid file path. If the path is dynamically sourced from a previous node, inspect the output of that node to confirm the field is populated. Also verify that Read File is enabled.

File not found error

The file path resolved by File Path Expression does not point to an existing, accessible file. Confirm the path is correct and that the workflow runtime has read permissions for the target directory and file.

Base64 output is rejected by target API

Some APIs expect a data URI prefix (e.g., data:image/png;base64,) rather than a raw Base64 string. If the API requires this format, add a String Operation node after this node to prepend the appropriate prefix. Conversely, some APIs expect raw Base64 without any prefix - check the target API documentation to confirm the expected format.

Output is larger than expected

This is expected behavior. Base64 encoding produces output that is approximately 33% larger than the source binary file. If payload size is a constraint, consider compressing the file before encoding or confirming whether the target system accepts a binary upload method instead.

---

Test Cases

• Given: Image file at path uploads/sample.jpg with Read File = On - Expected: Base64 string output containing the encoded image data, stored in the result column.
• Given: PDF file with Include Metadata = On - Expected: Output includes Base64 string plus metadata fields (file name, size, MIME type).
• Given: Nonexistent file path - Expected: Error indicating file not found; no Base64 output produced.
• Given: Valid file with Option = Return result column only - Expected: Output contains only the Base64 string field, with no original input fields present.

---

Industry Applications

Industry	Challenge	How Node Helps	Outcome
Healthcare	APIs require diagnostic files as Base64 text	Encodes patient scans or reports for secure transmission	Enables integration with health data APIs securely
Finance	Digital signatures must be submitted in Base64 format	Converts files for compliant electronic document workflows	Simplifies compliance processes, reduces manual preparation
Marketing	Campaign automation needs inline images for emails	Encodes media assets into Base64 for embedding	Speeds campaign assembly, reduces upload errors

---

Related Nodes

• ConvertBase64ToFile - Decodes Base64 strings back into binary files, the inverse of this node.
• FileToText - Extracts readable text content from files before or after encoding.
• Send Email - Can receive Base64-encoded file data for inline attachment handling.