{"record":{"id":"caad98f622555e01","repo":"agentscope-ai/agentscope","slug":"please-install-pandas-to-use-the-excel-parser-you","errorCode":null,"errorMessage":"Please install pandas to use the Excel parser. You can install it by `pip install pandas` (or `pip install agentscope[rag]`).","messagePattern":"Please install pandas to use the Excel parser\\. You can install it by `pip install pandas` \\(or `pip install agentscope\\[rag\\]`\\)\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"src/agentscope/rag/_parser/_excel.py","lineNumber":245,"sourceCode":"        Returns:\n            `list[Section]`:\n                Sections in sheet order.  When ``separate_sheet=True``,\n                text sections carry ``{\"sheet\": \"<name>\"}`` metadata\n                and image sections add\n                ``{\"media_type\": \"image/...\"}``.  When\n                ``separate_sheet=False`` (default), all text is merged\n                into a single section with ``metadata={}``.\n\n        Raises:\n            `FileNotFoundError`: If ``file`` is a ``str`` pointing to\n                a path that does not exist.\n            `ImportError`: If :mod:`pandas` is not installed.\n            `ValueError`: If the bytes cannot be parsed.\n        \"\"\"\n        try:\n            import pandas as pd\n        except ImportError as e:\n            raise ImportError(\n                \"Please install pandas to use the Excel parser. \"\n                \"You can install it by `pip install pandas` (or \"\n                \"`pip install agentscope[rag]`).\",\n            ) from e\n\n        if isinstance(file, str):\n            excel_file = pd.ExcelFile(file)\n        else:\n            excel_file = pd.ExcelFile(io.BytesIO(file))\n\n        workbook = None\n        try:\n            if self.include_image:\n                try:\n                    from openpyxl import load_workbook\n\n                    if isinstance(file, str):\n                        workbook = load_workbook(file)","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/rag/_parser/_excel.py#L227-L263","documentation":"The Excel parser needs the optional pandas dependency. Importing pandas inside parse() failed, so an ImportError with install instructions is raised, chained to the original ImportError.","triggerScenarios":"Calling ExcelParser.parse(...) in an environment where pandas is not installed (agentscope installed without the [rag] extra).","commonSituations":"pip install agentscope without extras; slim Docker images; CI environments missing optional deps.","solutions":["pip install pandas (or pip install 'agentscope[rag]')","Add pandas to your requirements/pyproject alongside agentscope","Pre-check availability and give users a friendly message if Excel parsing is optional in your app"],"exampleFix":"# before\nparser = ExcelParser()  # later: ImportError at parse()\n\n# after\n# pip install 'agentscope[rag]'\nparser = ExcelParser()","handlingStrategy":"validation","validationCode":"try:\n    import pandas  # noqa\n    pandas_ok = True\nexcept ImportError:\n    pandas_ok = False\nif not pandas_ok:\n    raise SystemExit('pip install agentscope[rag] to enable Excel parsing')","typeGuard":null,"tryCatchPattern":"try:\n    parser.parse(f)\nexcept ImportError as e:\n    if 'pandas' not in str(e):\n        raise\n    logger.warning('Excel parsing disabled: install pandas')","preventionTips":["Install agentscope[rag] in environments that parse documents","Feature-detect optional parsers at startup"],"tags":["agentscope","rag","excel","missing-dependency","pandas"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}