What the agent does
The message comes from xlrd 2.0, which removed every reader except the one for the old binary .xls format. Code that calls xlrd.open_workbook() on an .xlsx file worked through xlrd 1.2 and raises xlrd.biffh.XLRDError: Excel xlsx file; not supported from 2.0 on. The agent starts in the manifest to see why the project got the new version. In a command line viewer like kristianperkins/x_x, setup.py lists requirements = ["xlrd", "click", "six"] with no version bound, so every fresh pip install resolves xlrd to a 2.x release, and the README's own first example, x_x dead_guys.xlsx, stops working.
It reproduces the failure the way a user meets it. The repository ships no sample workbook and no tests, so the agent installs the package into a clean virtualenv, writes a three-row .xlsx with a text cell, an integer, a date and one empty cell, and runs the x_x console script on it. The program prints Excel xlsx file; not supported and exits with status 1. There is no traceback, and the agent explains why: cli() in x_x/x_x.py wraps the open_workbook call in except Exception as e: sys.exit(e), so the error class never reaches the terminal. It confirms the class by calling xlrd.open_workbook directly.
The fix is a second reader, and the agent fits it to the code that is there. x_x/cursor.py has two cursors: XCursor, which reads an xlrd sheet through sheet.nrows, sheet.row(n) and each cell's .value, and CSVCursor, which takes a plain list of rows. An openpyxl worksheet opened with load_workbook(filename, read_only=True, data_only=True) yields plain rows from iter_rows(values_only=True), so they go straight into CSVCursor and no third class is needed. To choose the reader it asks xlrd.inspect_format(filename), which reads the file's content and answers xlsx or xls, since cli() treats every name that does not end in .csv as Excel and an extension check would miss a misnamed file. It adds openpyxl to the requirements list in setup.py and leaves the .xls branch, including its encoding_override argument, as it was.
Then it compares what the two libraries print for the same workbook, because a new reader that runs is not yet the old behaviour. With xlrd pinned to 1.2.0 the sample shows the integer as 59.0, the date as the serial number 24823.0 and the empty cell as blank. Through openpyxl the same cells come back as 59, 1967-12-17 00:00:00 and None. The agent maps None to an empty string so the table does not print the word, and it reports the number and date differences instead of converting them back, since the new output is closer to what the spreadsheet shows. It runs the script once more with -h 0 to check that the heading row option still works on the new path.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This project fails on .xlsx files with: xlrd.biffh.XLRDError: Excel xlsx file; not supported. Fix it without pinning xlrd below 2. Read the manifests and say which xlrd version a fresh install resolves to and whether anything bounds it. Find every xlrd.open_workbook call and every place the code touches an xlrd sheet or cell (nrows, row, cell_value, ctype, xldate_as_tuple, sheet_by_index, sheet_by_name). In a clean virtualenv, reproduce the failure by running the real entry point on an .xlsx file; if the repository has no sample workbook, create a small one with text, an integer, a float, a date, a formula and an empty cell. Read .xlsx with openpyxl and keep xlrd for .xls; pick the reader from the file's content, not only its extension. Reuse the project's existing row abstraction where one exists instead of adding a parallel one. Then install xlrd 1.2.0 in a second virtualenv, run the same workbook through the old code, and list every difference in output between old and new (number formatting, dates, empty cells, formulas). Fix the differences that would print wrong data and report the rest; do not hide them. Add openpyxl to the declared dependencies. If the project has tests, run them; if it has none, add one that reads a generated .xlsx and one that reads a .xls only if you can produce a real .xls file. Open a pull request with the output before and after.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request with a small diff: the reader choice in cli(), openpyxl added to the requirements list in setup.py, and a test that builds a workbook and checks the rows the cursor returns. The description shows the one-line error and exit status from before, the rendered table from after, and a side-by-side of the xlrd 1.2.0 output and the openpyxl output for the same file. It names the two differences it kept, integers without a trailing .0 and dates as dates, so a maintainer who depended on the old strings can say so.
The reviewer checks three things. First, that .xls still goes through xlrd and that nothing in that branch moved. Second, the formula caveat: data_only=True returns the value Excel last calculated and stored, which is what xlrd returned too, but a workbook written by a script and never opened in Excel has no stored values, and those cells read as empty. Third, whether the broad except Exception should stay. The agent leaves it, because narrowing it changes what users see for unrelated failures, and says so.
The description also states what was not tested. A real .xls file cannot be produced with xlrd or openpyxl, so unless the repository holds one, the binary path is covered by reading the code and by the fact that it is unchanged.
Run it on every error-tracker issue with this XLRDError
In a service that parses uploads, this error shows up in the error tracker the first time someone uploads an .xlsx after an image rebuild pulled xlrd 2. Sentry signs its own webhook requests and cannot add the Authorization: Bearer header a Rush webhook trigger needs, so point Sentry at a small handler on your server. The handler keeps issues whose title contains Excel xlsx file; not supported and forwards the payload to the trigger's URL with the trigger's secret. The event arrives after the saved prompt, so the agent sees the stack frame that made the call.
For tools nobody monitors, search your repositories for xlrd.open_workbook and start one run per match through the API with the body above. Send a request_id that is a UUID v5 of the repository name so a retried script does not start the same fix twice.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The answer most people find is one of two lines: pin xlrd==1.2.0, or swap the import for openpyxl. The pin keeps a release that gets no fixes, and the swap silently changes what every cell looks like. Seeing that takes a clean install of both versions and one workbook read through each, which is quick in a fresh sandbox and tedious in a virtualenv that already has years of packages in it. The run keeps both outputs, so the difference in dates and numbers is in the record instead of in a bug report a month later.
It is also a fix that tends to exist in many places at once. Internal scripts, ETL jobs and admin tools all picked up the same unpinned dependency. Each run works in its own sandbox on its own repository, so twenty of them can be started from one script, and each pull request carries its own before and after.
Frequently asked questions
Can I just pin xlrd to 1.2.0?
It works for now and it is the wrong fix to keep. The xlrd maintainers removed the .xlsx reader on purpose and recommend openpyxl for that format. A pin also has to be repeated in every manifest and image that installs the project. The agent is told not to pin, and it installs 1.2.0 only in a second virtualenv to compare output.
I call pandas.read_excel, not xlrd. Is this the same problem?
It is the same cause with a shorter fix. Older pandas used xlrd for every Excel file; current pandas reads .xlsx with openpyxl when it is installed. The agent finds the read_excel calls, adds openpyxl to the dependencies, and passes engine="openpyxl" only where the pandas version in the lockfile needs it.
Will dates and numbers look different after the change?
Usually yes. xlrd returns every number as a float and every date as a serial number unless the code converts it, while openpyxl returns integers as integers and dates as datetime values. The pull request lists each difference it found on a sample workbook. If downstream code parses the old strings, tell the agent in a follow-up and it converts them back in one place.
More jobs like this: Fix a bug from an alert
- Fix "load() missing 1 required positional argument: 'Loader'" in PyYAML (PyYAML)
- Replace PyCrypto With PyCryptodome in a Python Project (PyCrypto)
- Fix openai.ChatCompletion Errors by Migrating to the v1 Client (OpenAI Python SDK)
- Trim Message History in a LangGraph Agent (LangGraph)
- Add Connection Pooling to a GORM App (GORM)
- Add Connection Pooling Limits to a Prisma App on Serverless (Prisma)