Error Handling

Proper error handling is essential when working with file conversions. This guide covers common errors and how to handle them.

Error Types

File Not Found

Occurs when a file path doesn't exist.

try {
  const markdown = await convertToMarkdown('./nonexistent.pdf');
} catch (error) {
  if (error.message.includes('File not found')) {
    console.error('File does not exist');
  }
}

Invalid Format

Occurs when the file format is not supported or corrupted.

try {
  const markdown = await convertToMarkdown(buffer);
} catch (error) {
  if (error.message.includes('Failed to convert')) {
    console.error('Unable to convert this file format');
  }
}

Invalid PDF Input

Occurs when a buffer is submitted as PDF data but does not contain a valid PDF header.

import { convertToMarkdown } from '@cognipeer/to-markdown';

try {
  await convertToMarkdown(invalidPdfBuffer, {
    fileName: 'document.pdf'
  });
} catch (error) {
  if (error.message.includes('PDF')) {
    console.error('Invalid PDF data supplied');
  }
}

Invalid PDF input now fails fast with an explicit error instead of hanging during conversion. If your application accepts uploaded buffers, handle this as a validation failure and return a clear message to the caller.

Base64 Decoding Error

Occurs when base64 data is malformed.

try {
  const markdown = await convertToMarkdown(invalidBase64);
} catch (error) {
  if (error.message.includes('Failed to convert base64')) {
    console.error('Invalid base64 data');
  }
}

Best Practices

Always Use Try-Catch

Wrap conversion calls in try-catch blocks:

async function safeConvert(input: ConverterInput): Promise<string | null> {
  try {
    return await convertToMarkdown(input);
  } catch (error) {
    console.error('Conversion failed:', error.message);
    return null;
  }
}

Validate Input

Check input before conversion:

import { existsSync } from 'fs';

function validateInput(filePath: string): boolean {
  if (!existsSync(filePath)) {
    throw new Error(`File not found: ${filePath}`);
  }
  return true;
}

try {
  validateInput('./document.pdf');
  const markdown = await convertToMarkdown('./document.pdf');
} catch (error) {
  console.error('Validation failed:', error.message);
}

Provide Helpful Context

Include context in error messages:

async function convertWithContext(
  filePath: string,
  context: string
): Promise<string> {
  try {
    return await convertToMarkdown(filePath);
  } catch (error) {
    throw new Error(
      `Failed to convert ${context}: ${error.message}`
    );
  }
}

Log Errors Appropriately

Use proper logging for production:

import { convertToMarkdown } from '@cognipeer/to-markdown';

async function convertWithLogging(input: ConverterInput) {
  try {
    const result = await convertToMarkdown(input);
    logger.info('Conversion successful');
    return result;
  } catch (error) {
    logger.error('Conversion failed', {
      error: error.message,
      input: typeof input === 'string' ? input : 'Buffer',
      stack: error.stack
    });
    throw error;
  }
}

Common Scenarios

Batch Processing

Handle errors in batch operations:

async function convertMultiple(files: string[]): Promise<Map<string, string>> {
  const results = new Map<string, string>();

  for (const file of files) {
    try {
      const markdown = await convertToMarkdown(file);
      results.set(file, markdown);
    } catch (error) {
      console.error(`Failed to convert ${file}:`, error.message);
      // Continue with next file
    }
  }

  return results;
}

Retry Logic

Implement retry for transient failures:

async function convertWithRetry(
  input: ConverterInput,
  maxRetries: number = 3
): Promise<string> {
  let lastError: Error;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await convertToMarkdown(input);
    } catch (error) {
      lastError = error;
      console.warn(`Attempt ${i + 1} failed, retrying...`);
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
    }
  }

  throw new Error(
    `Failed after ${maxRetries} attempts: ${lastError.message}`
  );
}

Fallback Handling

Provide fallback behavior:

async function convertWithFallback(input: ConverterInput): Promise<string> {
  try {
    return await convertToMarkdown(input);
  } catch (error) {
    console.warn('Conversion failed, using fallback');

    // Return placeholder or default content
    if (Buffer.isBuffer(input)) {
      return '# Conversion Failed\n\nUnable to convert binary content.';
    } else {
      return `# Conversion Failed\n\nFile: ${input}\nError: ${error.message}`;
    }
  }
}

Error Messages Reference

Error Message	Cause	Solution
"File not found: ..."	File doesn't exist at path	Check file path
"Failed to convert base64: ..."	Invalid base64 data	Verify base64 encoding
"Invalid input format"	Input is neither string nor Buffer	Use correct input type
"Failed to convert PDF: ..."	PDF processing error	Check PDF file integrity
"Failed to convert DOCX: ..."	DOCX processing error	Ensure valid DOCX format
"Failed to convert Excel: ..."	Excel processing error	Verify Excel file format
"Failed to parse JSON: ..."	Malformed JSON document	Validate the JSON syntax
"Failed to convert EPUB: ..."	Missing or invalid OPF manifest	Confirm the file is a valid EPUB

See Also

• API Overview
• Format Support