Troubleshooting

Error: Module <module_name> not found. Please install it using pip.
Error: Try: pip install <module_name>
Error: This module is required for the requested operation.

1. Install the specific module mentioned in the error:
   pip install <module_name>
   
2. Install all core dependencies using UV (recommended):
   cd swissknife
   pip install uv --upgrade
   uv sync
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
3. Install dependencies manually:
   uv add pypandoc pillow imageio-ffmpeg patoolib google-genai pypdf
   

• pypandoc - Required for document conversions
• PIL (install with pip install Pillow) - Required for image conversions
• imageio_ffmpeg (install with pip install imageio-ffmpeg) - Required for audio/video conversions
• patoolib - Required for archive operations
• google.genai (install with pip install google-generativeai) - Required for AI summarization
• pypdf - Required for PDF merge/split operations

Error: Conversion failed: RuntimeError: Pandoc not found

Error: xelatex not found

​

Install LaTeX

1. Download MiKTeX from miktex.org
2. Run the installer and follow the setup wizard
3. MiKTeX will automatically install packages on-demand

choco install texlive

# Full installation (recommended)
sudo apt update
sudo apt install -y texlive-latex-base texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra

# Minimal installation (faster)
sudo apt install -y texlive-latex-base texlive-fonts-recommended

brew install --cask basictex
export PATH=/Library/TeX/texbin:$PATH

​

Install Pandoc

# Using pypandoc's built-in installer
python -c "import pypandoc; pypandoc.download_pandoc()"

• Windows: Download from pandoc.org
• Linux: sudo apt install pandoc
• macOS: brew install pandoc

​

Verify Installation

pandoc --version
xelatex --version

Error: Conversion failed: FileNotFoundError: ffmpeg not found

Error: subprocess returned non-zero exit status

1. Ensure imageio-ffmpeg is installed:
   pip install imageio-ffmpeg
   
   This package bundles ffmpeg, so no separate installation is needed.
2. Verify the installation:
   python -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())"
   
3. For unsupported codec errors:
   • Some video formats may require specific codecs
   • Try converting to a common format first (e.g., MP4)
   • Use --preserve-original flag to keep the source file

• Audio: MP3, WAV, FLAC, AAC, OGG, M4A (solution.py:40, 75-78)
• Video: MP4, AVI, MKV, MOV, WMV, FLV, WEBM, GIF (solution.py:42, 71-74, 79-80)

Error: Conversion failed: patool error: could not find an executable program to extract format 7z

Error: unrar not found

​

Install 7-Zip (for .7z format)

sudo apt update
sudo apt install p7zip-full

brew install p7zip

1. Download from 7-zip.org
2. Install and add to system PATH:
   • Search “Edit the system environment variables”
   • Add C:\Program Files\7-Zip to Path variable

​

Install RAR/UnRAR (for .rar format)

sudo apt update
sudo apt install unrar rar

brew install unrar rar

1. Download from rarlab.com
2. Extract to a folder (e.g., C:\Tools\RAR)
3. Add to system PATH

​

Verify Installation

7z --version
unrar --version

• .zip - Works without external tools
• .tar.gz - Works on most systems

Error: GOOGLE_API_KEY environment variable is not set.

1. Get an API key:
   • Sign up at aistudio.google.com
   • Create a new project
   • Generate an API key
2. Set the environment variable: Linux/macOS:
   export GOOGLE_API_KEY="your_api_key_here"
   
   # Make it permanent (add to ~/.bashrc or ~/.zshrc)
   echo 'export GOOGLE_API_KEY="your_api_key_here"' >> ~/.bashrc
   source ~/.bashrc
   
   Windows (Command Prompt):
   set GOOGLE_API_KEY=your_api_key_here
   
   # Make it permanent
   setx GOOGLE_API_KEY "your_api_key_here"
   
   Windows (PowerShell):
   $env:GOOGLE_API_KEY="your_api_key_here"
   
   # Make it permanent
   [System.Environment]::SetEnvironmentVariable('GOOGLE_API_KEY', 'your_api_key_here', 'User')
   
3. Verify the setup:
   python -c "import os; print('API key set' if os.environ.get('GOOGLE_API_KEY') else 'API key not found')"
   

Error: File size (XXX.XMB) exceeds maximum limit of 100MB

1. Compress or optimize the file:
   • For PDFs: Use a PDF compression tool
   • For documents: Remove embedded images or media
   • For images in PDFs: Reduce image quality
2. Extract text before summarizing:
   # Convert to plain text first (usually much smaller)
   python solution.py convert large_file.pdf extracted.txt
   python solution.py summarize extracted.txt --length medium
   
3. Split the document:
   # For PDFs, split into smaller sections
   python solution.py split large_document.pdf "1-50"
   python solution.py split large_document.pdf "51-100"
   
   # Summarize each part separately
   python solution.py summarize large_document_part1.pdf
   python solution.py summarize large_document_part2.pdf
   
4. Use a different file format:
   • Convert to a more efficient format before summarizing
   • Text-based formats (.txt, .md) are typically smaller

• The limit is enforced at solution.py:166
• File size is calculated as file_size_mb = input_abs.stat().st_size / (1024 * 1024)

Error: File processing timed out

1. Reduce file size:
   • Large files take longer to process
   • Follow solutions in “File size limit errors” above
2. Check internet connection:
   • Slow upload speeds can delay processing
   • Ensure stable internet connectivity
3. Simplify the document:
   • Complex formatting increases processing time
   • Convert to plain text first:
     python solution.py convert complex.pdf simple.txt
     python solution.py summarize simple.txt
     
4. Retry the operation:
   • Temporary server issues may cause timeouts
   • Wait a moment and try again
5. Use a shorter summary length:
   # Short summaries may process faster
   python solution.py summarize document.pdf --length short
   

• Timeout is set at 300 seconds (solution.py:181)
• The tool polls the processing status every 2 seconds (solution.py:182)
• Processing states: PROCESSING → ACTIVE (success) or FAILED (error)

Error: Permission denied

Error: [Errno 13] Permission denied: 'output.pdf'

• Trying to write to a protected directory
• Output file is open in another program
• Insufficient file system permissions

1. Close the output file:
   • Ensure the output file isn’t open in another application
   • Close PDF readers, text editors, or media players
2. Check directory permissions:
   # Linux/macOS: Verify write permissions
   ls -la /path/to/output/directory
   
   # Give write permission if needed
   chmod u+w /path/to/output/directory
   
3. Write to a different location:
   # Use your home directory or a temp location
   python solution.py convert input.pdf ~/output.pdf
   
4. Run with appropriate permissions:
   # Linux/macOS: Use sudo only if absolutely necessary
   sudo python solution.py convert input.pdf /protected/path/output.pdf
   
5. Check input file permissions:
   # Ensure you can read the input file
   chmod u+r input_file.pdf
   
6. For Windows:
   • Run Command Prompt or PowerShell as Administrator
   • Right-click the application → “Run as administrator”
   • Check if antivirus is blocking file access

Output file /path/to/output.pdf exists. Overwrite? (y/N):

1. Confirm overwrite:
   • Type y and press Enter to overwrite
   • Type n or press Enter to cancel
2. Use a different output name:
   python solution.py convert input.pdf output_v2.pdf
   
3. Move or backup the existing file:
   mv output.pdf output_backup.pdf
   python solution.py convert input.pdf output.pdf
   
4. For batch operations:
   • The tool will prompt for each file that exists
   • Consider using a fresh output directory
   • Or move existing files before starting

Error: Unsupported input file type: /path/to/file

Error: Cannot convert <type> to <extension>

1. Check supported formats:
   • Documents: PDF, DOCX, DOC, TXT, MD, EPUB, PPTX, XLSX, HTML, TEX, XML, and more (solution.py:36, 52)
   • Images: JPG, JPEG, PNG, WEBP, GIF, BMP, TIFF, PDF (solution.py:38, 52)
   • Audio: MP3, WAV, FLAC, AAC, OGG, M4A (solution.py:40, 52)
   • Video: MP4, AVI, MKV, MOV, WMV, FLV, WEBM (solution.py:42, 52)
   • Archives: ZIP, TAR, GZ, BZ2, 7Z, RAR (solution.py:44, 52)
2. Verify file extension:
   • Ensure the file has the correct extension
   • Rename if necessary: mv file.unknown file.pdf
3. Try a two-step conversion:
   # If direct conversion isn't supported, use an intermediate format
   python solution.py convert input.xyz intermediate.pdf
   python solution.py convert intermediate.pdf output.docx
   
4. Check if file is corrupted:
   • Try opening the file in its native application
   • Re-download or re-create the file if needed

• PDF to other document formats is not supported
• Some conversions require specific dependencies (see installation guide)

Info: No files with extension .xxx found in /path/to/directory

1. Verify the directory path:
   # List files to confirm location
   ls /path/to/input/directory
   
2. Check extension format:
   # Both formats work (with or without dot)
   python solution.py batch-convert ./input ./output .txt .pdf
   python solution.py batch-convert ./input ./output txt pdf
   
3. Verify file extensions:
   # Files must have exact extension match (case-sensitive on Linux/macOS)
   # If files are .TXT, use:
   python solution.py batch-convert ./input ./output .TXT .pdf
   
4. Use absolute paths:
   python solution.py batch-convert /home/user/docs/input /home/user/docs/output .docx .pdf