Skip to main content
Running into problems? This guide covers common issues and how to resolve them.

​
Common Issues

​
File Format Not Auto-Detected

Problem: After selecting a file, no input format is automatically selected.
The file might have an incorrect or missing extension.Steps:
  1. Check that your file has the correct extension (e.g., .png, .mp4)
  2. If the extension is missing or wrong, rename the file
  3. Re-upload the file to Convert to it!
Example: A PNG file named image without an extension won’t be detected. Rename it to image.png.
Use the search box to find and select your format manually.Steps:
  1. Look at your file’s extension (e.g., .docx, .svg)
  2. Type the extension or format name in the input search box
  3. Click the matching format from the filtered list
This works even when auto-detection fails.
Your operating system might be reporting an incorrect MIME type.Steps:
  1. Try opening the file in its native application first
  2. Re-save it from that application
  3. Upload the newly saved file
This often fixes MIME type mismatches.

​
”All Input Files Must Be of the Same Type” Error

Problem: You selected multiple files but got an error message. Solution:
1

Verify File Types

All selected files must have the same MIME type and format.Incorrect: Selecting image.png and video.mp4 together
Correct: Selecting image1.png and image2.png together
2

Convert Files Separately

If you need to convert different file types:
  1. Convert each file type in separate batches
  2. Select all PNG files first, convert them
  3. Then select all MP4 files, convert them
3

Check Hidden Extensions

Sometimes files that look the same aren’t:
  • document.docx and document.doc are different formats
  • image.jpg and image.jpeg should work together (same MIME type)

​
Conversion Fails - “Failed to Find Conversion Route”

Problem: After clicking Convert, you get an alert saying no route was found.
The specific input/output combination might not have a working route.Solutions:
  • Try converting to an intermediate format first (e.g., if PNG → DOCX fails, try PNG → PDF → DOCX)
  • Check the Supported Formats page for compatible formats
  • In Advanced mode, try different handlers for the same format
A required handler might have failed to load.Solutions:
  • Check browser console (F12 → Console tab) for error messages
  • Refresh the page to reinitialize all handlers
  • Clear browser cache and reload
  • Try a different browser - Chrome, Firefox, and Edge are recommended
The converter tried multiple routes but they all failed.Solutions:
  • Check the browser console for specific error messages
  • Try converting a smaller or simpler file
  • Switch between Simple and Advanced mode
  • File might be corrupted - try re-creating or re-exporting it

​
Conversion Takes Too Long

Problem: The conversion has been running for several minutes without completing. Expected Times:
  • Small images (< 5MB): 1-5 seconds
  • Large images (> 20MB): 10-30 seconds
  • Short videos (< 1 min): 30-60 seconds
  • Long videos (> 5 min): 2-10 minutes
  • Complex multi-step routes: Add 5-30 seconds per step
Video and audio processing can be slow, especially:
  • Long videos (> 5 minutes)
  • High-resolution videos (4K, 8K)
  • Multi-step conversion routes
What to do:
  • Wait for the process to complete
  • Check the popup for route progress
  • Don’t close or refresh the browser
Reduce file size before converting:For Images:
  • Resize to a smaller resolution first
  • Reduce quality/compression
For Videos:
  • Trim to a shorter duration
  • Lower the resolution (1080p → 720p)
  • Reduce frame rate if possible
In Advanced mode, select handlers that support direct conversion:
  • Avoid multi-step routes if possible
  • Choose handlers known for the specific conversion (e.g., FFmpeg for video)

​
Output File is Empty or Corrupted

Problem: The conversion completes but the downloaded file is broken or empty.
Make sure your input file is valid:Steps:
  1. Open the original file in its native application
  2. If it won’t open, the file is corrupted
  3. Try re-downloading or re-creating the file
  4. Try a different input file to test
Some conversions might not work as expected:
  • Try converting to a different output format first
  • Use an intermediate format (e.g., PNG → PDF instead of PNG → DOCX)
  • Check if the conversion is logically possible
Some handlers work better in certain browsers:Recommended browsers:
  • Chrome (best compatibility)
  • Firefox
  • Edge
Less reliable:
  • Safari (limited WebAssembly support)
  • Mobile browsers (memory constraints)

​
First Load is Very Slow

Problem: The page takes 30-60 seconds to load the first time. This is expected behavior!
On first load, Convert to it! builds a format list by querying all 60+ handlers. This includes:
  • Initializing WebAssembly modules
  • Loading dependencies
  • Building the conversion graph
Subsequent loads use cached data and are much faster.
To speed up future loads:
  1. Keep the cache: Don’t clear browser data for convert.to.it
  2. For developers: Use printSupportedFormatCache() in the console and save output to cache.json

​
Browser Console Shows Errors

Problem: Red error messages appear in the browser console (F12).
Severity: Warning (not critical)This is normal on first load. The handler will initialize and cache its formats.Action: No action needed unless it persists after page refresh.
Severity: WarningA handler failed to initialize properly.Solutions:
  • Refresh the page
  • Check internet connection (some handlers load external resources)
  • Try a different browser
  • The converter can still work with other handlers
Severity: ErrorThe handler produced no output for this conversion.Solutions:
  • The route is marked as a dead end and alternative routes are tried
  • If all routes fail, try a different intermediate format
  • Check if the input file is valid
Severity: CriticalHandler initialization failed due to missing dependencies.Solutions:
  • Check internet connection
  • Clear cache and reload
  • Update your browser to the latest version
  • Try a different browser (Chrome recommended)

​
Understanding Conversion Routes

​
Multi-Step Routing

Convert to it! uses graph traversal to find conversion paths. Sometimes the route is not obvious: 
PNG → JPEG
(handled by ImageMagick)
The more steps in a route, the higher the chance of failure. Each step introduces a potential point of failure.

​
Dead Ends and Fallbacks

When a conversion route fails:
  1. Route is marked as dead end - Won’t be tried again this session
  2. Alternative route is found - Graph traversal continues
  3. All routes exhausted - “Failed to find conversion route” error
You can see attempted routes in the browser console and popup messages.

​
Format-Specific Issues

​
PDF Conversion Issues

PDF to Image:
  • Multi-page PDFs export as multiple image files
  • Quality depends on PDF resolution
  • Some PDFs with complex vector graphics may not render perfectly
Image/Video to PDF:
  • Resulting PDF embeds the image/video frame
  • Not searchable or editable text
  • Large files may take time to process

​
When to Report a Bug

According to the project guidelines:
NOT a bug: “Converting X to Y doesn’t work”This is expected for unsupported format combinations.
IS a bug: “Converting X to Y works but not how I expected”If the conversion succeeds but produces unexpected output, that’s worth reporting!

​
Before Reporting a Bug

1

Check Existing Issues

Search the GitHub Issues to see if it’s already reported.
2

Gather Information

Collect:
  • Input file format and size
  • Output format selected
  • Browser and version
  • Console error messages (F12 → Console)
  • Conversion route shown in popup
3

Test Reproducibility

  • Try the conversion again
  • Try with a different input file
  • Try in a different browser
  • Note if the issue is consistent
4

Submit Bug Report

Include all gathered information in your bug report on GitHub.Good bug report:
“Converting PNG to PDF produces blank output. Input: 1920x1080 PNG (2MB). Browser: Chrome 120. Console shows ‘Output is empty’ from htmlEmbed handler. Tested with 3 different PNG files - same result.”
Bad bug report:
“PNG to PDF doesn’t work”

​
Requesting New Formats

Want a format added? Read the project’s requirements:
Simply asking for a format is NOT a valid request!Format requests require substantial research and documentation.

​
Valid Format Request Requirements

1

Check for Duplicates

  • Search existing issues
  • Verify the format isn’t already supported
  • Check the Supported Formats page
2

Explain Expected Behavior

Describe what the conversion should do:
  • What medium is it (image, audio, video, document)?
  • How should it convert to/from other formats?
  • What’s the expected output?
Example: “HEIC is an image format that should convert to/from PNG, JPEG like other raster images.”
3

Provide Implementation References

Link to:
  • Existing browser-based solutions (if any)
  • Libraries with compatible licenses (GPL-2.0)
  • Technical specifications or documentation
  • Example files for testing

​
Getting Additional Help

GitHub Issues

Report bugs and request features (following guidelines above)

YouTube Video

Semi-technical overview of how Convert to it! works

Source Code

Explore the codebase for technical details

Using the Converter

Review the complete usage guide

​
Browser Compatibility

For best results, use the latest version of Chrome or Firefox on a desktop computer with at least 4GB of RAM.

Build docs developers (and LLMs) love

Get started for freeTalk to us