{"record":{"id":"5bdc1658ba2d3a2b","repo":"microsoft/markitdown","slug":"error-converting-ipynb-file-str-e","errorCode":null,"errorMessage":"Error converting .ipynb file: {str(e)}","messagePattern":"Error converting \\.ipynb file: (.+?)","errorType":"exception","errorClass":"FileConversionException","httpStatus":null,"severity":"error","filePath":"packages/markitdown/src/markitdown/converters/_ipynb_converter.py","lineNumber":94,"sourceCode":"\n                elif cell_type == \"code\":\n                    # Code cells are wrapped in Markdown code blocks\n                    md_output.append(f\"```python\\n{''.join(source_lines)}\\n```\")\n                elif cell_type == \"raw\":\n                    md_output.append(f\"```\\n{''.join(source_lines)}\\n```\")\n\n            md_text = \"\\n\\n\".join(md_output)\n\n            # Check for title in notebook metadata\n            title = notebook_content.get(\"metadata\", {}).get(\"title\", title)\n\n            return DocumentConverterResult(\n                markdown=md_text,\n                title=title,\n            )\n\n        except Exception as e:\n            raise FileConversionException(\n                f\"Error converting .ipynb file: {str(e)}\"\n            ) from e\n","sourceCodeStart":76,"sourceCodeEnd":97,"githubUrl":"https://github.com/microsoft/markitdown/blob/fd239d5d2be43d9b68329730206b9312c7d5a388/packages/markitdown/src/markitdown/converters/_ipynb_converter.py#L76-L97","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the {str(e)} portion of the message — it names the actual underlying failure (e.g. ValidationError from nbformat, KeyError on a mime type)","Validate the notebook first: python -m nbformat.validate notebook.ipynb, and fix or re-export it from Jupyter","Upgrade nbformat/nbconvert to a version matching the notebook's nbformat version","If a single cell's custom output breaks conversion, open the notebook, clear that output, and re-save"],"exampleFix":"# before\nresult = MarkItDown().convert(\"weird.ipynb\")  # FileConversionException: Error converting .ipynb file: ...\n\n# after: validate and repair first\nimport nbformat\nnb = nbformat.read(\"weird.ipynb\", as_version=4)\nnbformat.validate(nb)  # raises with a precise schema error\nnbformat.write(nb, \"weird.ipynb\")\nresult = MarkItDown().convert(\"weird.ipynb\")","handlingStrategy":"validation","validationCode":"import nbformat\n\ndef notebook_is_convertible(path: str) -> bool:\n    try:\n        nb = nbformat.read(path, as_version=4)\n        nbformat.validate(nb)\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"from markitdown import MarkItDown, FileConversionException\n\ntry:\n    result = MarkItDown().convert(\"nb.ipynb\")\nexcept FileConversionException as e:\n    # str(e) embeds the underlying cause after 'Error converting .ipynb file: '\n    logger.warning(\"notebook rejected: %s\", e)","preventionTips":["Validate notebooks with nbformat.validate before conversion in batch pipelines","Clear outputs of exotic custom mime types when exporting notebooks for ingestion","Log the full exception message; the embedded str(e) identifies the failing cell/output"],"tags":["ipynb","jupyter","conversion","validation","wrapper-exception"],"backgroundTag":null,"analyzedSha":"fd239d5d2be43d9b68329730206b9312c7d5a388","analyzedAt":"2026-08-14T15:47:51.745Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}