microsoft/markitdown · error · FileConversionException

Error converting .ipynb file: {str(e)}

Error message

Error converting .ipynb file: {str(e)}

What it means

The Jupyter converter loads the notebook with nbformat, iterates cells, and converts each cell's outputs to markdown inside a broad try block. Any unexpected failure — nbformat validation errors, exotic output mime types, nbconvert conversion of a cell raising, KeyError on malformed cell dicts — is wrapped in FileConversionException with the underlying message appended. The str(e) in the message is the key to diagnosing the real cause.

Source

Thrown at packages/markitdown/src/markitdown/converters/_ipynb_converter.py:94

                elif cell_type == "code":
                    # Code cells are wrapped in Markdown code blocks
                    md_output.append(f"```python\n{''.join(source_lines)}\n```")
                elif cell_type == "raw":
                    md_output.append(f"```\n{''.join(source_lines)}\n```")

            md_text = "\n\n".join(md_output)

            # Check for title in notebook metadata
            title = notebook_content.get("metadata", {}).get("title", title)

            return DocumentConverterResult(
                markdown=md_text,
                title=title,
            )

        except Exception as e:
            raise FileConversionException(
                f"Error converting .ipynb file: {str(e)}"
            ) from e

View on GitHub (pinned to fd239d5d2b)

Solutions

1. Read the {str(e)} portion of the message — it names the actual underlying failure (e.g. ValidationError from nbformat, KeyError on a mime type)
2. Validate the notebook first: python -m nbformat.validate notebook.ipynb, and fix or re-export it from Jupyter
3. Upgrade nbformat/nbconvert to a version matching the notebook's nbformat version
4. If a single cell's custom output breaks conversion, open the notebook, clear that output, and re-save

Example fix

# before
result = MarkItDown().convert("weird.ipynb")  # FileConversionException: Error converting .ipynb file: ...

# after: validate and repair first
import nbformat
nb = nbformat.read("weird.ipynb", as_version=4)
nbformat.validate(nb)  # raises with a precise schema error
nbformat.write(nb, "weird.ipynb")
result = MarkItDown().convert("weird.ipynb")

import nbformat

def notebook_is_convertible(path: str) -> bool:
    try:
        nb = nbformat.read(path, as_version=4)
        nbformat.validate(nb)
        return True
    except Exception:
        return False

from markitdown import MarkItDown, FileConversionException

try:
    result = MarkItDown().convert("nb.ipynb")
except FileConversionException as e:
    # str(e) embeds the underlying cause after 'Error converting .ipynb file: '
    logger.warning("notebook rejected: %s", e)

When it happens

Trigger: Calling convert() on a .ipynb stream where the JSON is valid but the notebook structure is malformed (missing required keys, cells of unknown type), nbformat version too old/too new for the installed nbformat library, or a cell output mime type that the per-cell converter does not handle (raising KeyError/ValueError internally). Also triggered by corrupt notebooks exported by nonstandard tools (e.g. VS Code extensions, JupyterLab forks).

Common situations: Batch-converting a directory of notebooks where one file is truncated or hand-edited; notebooks created with a much newer nbformat schema version than the installed library supports; notebooks containing widgets application/vnd.jupyter.widget-view+json outputs or other custom mime types.

Related errors

• Unsupported file URI: {uri}. Netloc must be empty or localho
• Unsupported URI scheme: {uri.split(':')[0]}. Supported schem
• File conversion failed after {len(attempts)} attempts:
• Not a file URL: {file_uri}
• Unknown feed type

AI-assisted analysis of microsoft/markitdown@fd239d5d2b (2026-08-14). Data as JSON: /api/errors/5bdc1658ba2d3a2b. Report an issue: GitHub.