Inspect Archive File

Lists all files contained in an archive without extracting them. This allows you to view the contents of compressed archives and verify file presence before extraction.

Common Properties

• Name - The custom name of the node.
• Color - The custom color of the node.
• Delay Before (sec) - Waits in seconds before executing the node.
• Delay After (sec) - Waits in seconds after executing node.
• Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

• File Path - Path to the archive file to inspect. Supports Zip, Tar, TarGz, RAR, and other archive formats.

Outputs

• List - An array containing the names of all files in the archive. Each element is a string representing a file path within the archive.

The output is stored in msg.list and contains the complete file paths as they appear in the archive, including directory structures.

How It Works

The Inspect Archive File node performs the following operations:

1. Opens the archive file at the specified path
2. Reads the archive's table of contents
3. Iterates through all entries in the archive
4. Collects the name/path of each file
5. Returns the complete list as an array

This operation does not extract any files - it only reads the archive's metadata.

Examples

Example 1: List Files in a Zip Archive

Inspect a Zip file and display its contents:

// Set the archive path
msg.archivePath = "/home/user/backups/project-backup.zip";

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Access the results in a subsequent Function node:

// The list is now available in msg.list
console.log("Archive contains", msg.list.length, "files:");
msg.list.forEach(file => {
    console.log(" -", file);
});

// Store for further processing
msg.fileCount = msg.list.length;

Example 2: Check for Specific File Existence

Check if a specific file exists in the archive:

// Archive to inspect
msg.archivePath = "/home/user/downloads/data-export.zip";
msg.requiredFile = "data/customers.csv";

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Add a Function node after inspection:

// Check if required file exists in the archive
msg.fileExists = msg.list.includes(msg.requiredFile);

if (msg.fileExists) {
    msg.message = `File '${msg.requiredFile}' found in archive`;
    msg.canProceed = true;
} else {
    msg.message = `File '${msg.requiredFile}' not found in archive`;
    msg.canProceed = false;

    // List similar files for debugging
    msg.similarFiles = msg.list.filter(f => f.includes('customers'));
}

Example 3: Filter Files by Extension

Find all files of a specific type in the archive:

// Set archive path
msg.archivePath = "/home/user/archives/documents.tar.gz";

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Add a Function node to filter results:

// Filter for specific file types
msg.pdfFiles = msg.list.filter(file => file.endsWith('.pdf'));
msg.excelFiles = msg.list.filter(file => file.endsWith('.xlsx') || file.endsWith('.xls'));
msg.imageFiles = msg.list.filter(file =>
    file.endsWith('.jpg') || file.endsWith('.png') || file.endsWith('.gif')
);

// Summary
msg.summary = {
    totalFiles: msg.list.length,
    pdfCount: msg.pdfFiles.length,
    excelCount: msg.excelFiles.length,
    imageCount: msg.imageFiles.length
};

console.log("Archive analysis:", msg.summary);

Example 4: Extract Directory Structure

Analyze the directory structure within the archive:

// Archive to analyze
msg.archivePath = "/home/user/backups/website-backup.zip";

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Add a Function node to analyze structure:

const path = require('path');

// Get unique directories
const directories = new Set();
msg.list.forEach(filePath => {
    const dir = path.dirname(filePath);
    if (dir !== '.') {
        directories.add(dir);

        // Add parent directories too
        let parts = dir.split('/');
        for (let i = 1; i < parts.length; i++) {
            directories.add(parts.slice(0, i).join('/'));
        }
    }
});

msg.directories = Array.from(directories).sort();
msg.directoryCount = msg.directories.length;
msg.fileCount = msg.list.length;

console.log(`Archive contains ${msg.fileCount} files in ${msg.directoryCount} directories`);

Example 5: Validate Archive Contents Before Processing

Validate that an archive contains all expected files:

// Define expected files
msg.archivePath = "/home/user/uploads/submission.zip";
msg.requiredFiles = [
    "application.pdf",
    "resume.pdf",
    "references.pdf"
];

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Add a Function node for validation:

// Check for all required files
msg.missingFiles = [];
msg.foundFiles = [];

msg.requiredFiles.forEach(requiredFile => {
    const found = msg.list.some(archiveFile =>
        archiveFile.endsWith(requiredFile)
    );

    if (found) {
        msg.foundFiles.push(requiredFile);
    } else {
        msg.missingFiles.push(requiredFile);
    }
});

msg.isValid = msg.missingFiles.length === 0;

if (msg.isValid) {
    msg.validationMessage = "All required files present in archive";
} else {
    msg.validationMessage = `Missing files: ${msg.missingFiles.join(', ')}`;
}

console.log(msg.validationMessage);

Example 6: Find Largest Files by Name Pattern

Identify files based on naming patterns:

// Archive to inspect
msg.archivePath = "/home/user/logs/server-logs.tar.gz";

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Add a Function node to find specific patterns:

// Find files matching patterns
msg.errorLogs = msg.list.filter(file => file.includes('error'));
msg.accessLogs = msg.list.filter(file => file.includes('access'));
msg.debugLogs = msg.list.filter(file => file.includes('debug'));

// Find files from specific date
const targetDate = '2024-01';
msg.monthlyLogs = msg.list.filter(file => file.includes(targetDate));

// Create report
msg.logReport = {
    totalLogs: msg.list.length,
    errorLogs: msg.errorLogs.length,
    accessLogs: msg.accessLogs.length,
    debugLogs: msg.debugLogs.length,
    monthlyLogs: msg.monthlyLogs.length
};

Example 7: Generate Archive Inventory

Create a detailed inventory of archive contents:

// Archive to inventory
msg.archivePath = "/home/user/backups/project-v2.0.zip";

Configure the Inspect Archive File node:

• File Path: {{msg.archivePath}}

Add a Function node to create inventory:

const path = require('path');

// Categorize files by extension
const fileTypes = {};
msg.list.forEach(filePath => {
    const ext = path.extname(filePath) || 'no-extension';
    if (!fileTypes[ext]) {
        fileTypes[ext] = [];
    }
    fileTypes[ext].push(filePath);
});

// Create inventory report
msg.inventory = {
    archiveName: path.basename(msg.archivePath),
    totalFiles: msg.list.length,
    fileTypes: Object.keys(fileTypes).map(ext => ({
        extension: ext,
        count: fileTypes[ext].length,
        files: fileTypes[ext]
    }))
};

// Sort by count
msg.inventory.fileTypes.sort((a, b) => b.count - a.count);

console.log("Archive Inventory:");
console.log(`Total Files: ${msg.inventory.totalFiles}`);
msg.inventory.fileTypes.forEach(type => {
    console.log(`  ${type.extension}: ${type.count} files`);
});

Usage Tips

1. Pre-Extraction Verification:

   • Always inspect archives before extracting to verify contents
   • Check for expected files to avoid processing incomplete archives
   • Validate file counts and types match expectations

2. Selective Extraction:

   • Use inspection results to determine which files to extract
   • Extract only needed files using the Extract File node
   • Save processing time and disk space

3. File Path Format:

   • File paths in the list include directory structure (e.g., "folder/subfolder/file.txt")
   • Use path parsing functions to analyze directory structure
   • Paths use forward slashes (/) regardless of the operating system

4. Performance:

   • Inspection is fast - it only reads metadata, not file contents
   • Much faster than extracting to check contents
   • Can be used repeatedly on the same archive without overhead

5. Archive Validation:

   • Verify archive integrity before processing
   • Check for expected file patterns and counts
   • Implement validation workflows before extraction

6. Integration with Other Nodes:

   • Use results to conditionally extract files
   • Pass file list to Extract File node for selective extraction
   • Use with Filter or Decision nodes to control workflow

Common Errors and Solutions

Error: "File path cannot be empty"

Cause: The File Path input is not provided or is empty.

Solution: Ensure you provide a valid path to the archive file.

Error: "Source path does not exist"

Cause: The specified archive file does not exist at the given path.

Solution:

• Verify the archive path is correct
• Check that the file exists and hasn't been moved or deleted
• Ensure proper path formatting

Error: Corrupted or invalid archive

Cause: The file is not a valid archive or is corrupted.

Solution:

• Verify the file is actually an archive (check file extension and content)
• Try opening the file with a standard archiving tool
• Re-download or re-create the archive if corrupted
• Check if the file download completed successfully

Error: Unsupported archive format

Cause: The archive format is not supported by the node.

Solution:

• Check the archive format is one of the supported types
• Convert the archive to a supported format if possible
• Use an appropriate tool for the specific archive type

Error: Permission denied

Cause: Insufficient permissions to read the archive file.

Solution:

• Ensure read permissions for the archive file
• Check file ownership and permissions
• Run the automation with appropriate user permissions

Error: Empty list returned

Cause: The archive exists but contains no files.

Solution:

• Verify the archive was created correctly
• Check if this is expected (empty archive)
• Validate the archive with external tools

Related Nodes

• Extract File - Extract specific files found in the inspection
• Unarchive - Extract all files from the archive
• Archive - Create archives with specific files
• Decompress - Decompress single compressed files