What the agent does
The agent reads the bot before it reads aiogram. arunpt/cowin-certificate-bot is a 275-line Telegram bot in bot.py plus a 60-line api_handler.py, with eleven @dp.message_handler and four @dp.callback_query_handler functions that walk a user through a phone number, an OTP and a certificate download. Its requirements.txt lists aiogram, aiohttp, aiofiles and python-dotenv with no versions. The imports at the top of bot.py are aiogram 2 throughout: from aiogram.utils import executor on line 8, FSMContext from aiogram.dispatcher on line 18, MemoryStorage from aiogram.contrib.fsm_storage.memory on line 19, State and StatesGroup from aiogram.dispatcher.filters.state on line 20, and executor.start_polling(dp, skip_updates=True) as the last line of the file.
A fresh install today resolves aiogram 3.31.0 and aiohttp 3.14.5, and import bot fails. In this bot the first line to break is line 4, from aiogram.types.reply_keyboard import KeyboardButton, ReplyKeyboardMarkup, with ModuleNotFoundError: No module named 'aiogram.types.reply_keyboard'; the error in the title is what the executor line raises four lines later, and it is the first error for the many bots whose first aiogram import is that one. Checked one line at a time against aiogram 3, five of the file's ten aiogram imports fail: the two module paths above, executor, FSMContext and filters from aiogram.dispatcher, and aiogram.contrib. The rest still resolve, including Bot, Dispatcher and every name imported from aiogram.types.
The agent then fixes the boundary. aiogram 3.0.0, published 2023-09-01, already has none of the five; aiogram 2.25.2, published 2023-10-06, is the last 2.x release, imports the whole file, and registers all fifteen handlers when bot.py is imported with a token in the environment. But 2.25.2 requires aiohttp<3.9.0, and aiohttp 3.8.6 fails to build on Python 3.12, so a pin to aiogram<3 holds only on Python 3.11 or older. aiogram 3 itself requires Python 3.10 or newer. Both facts go in the pull request, because the pin is the quick fix and the port is the lasting one.
For the port, the agent writes down where each name went, checked by importing it: aiogram.fsm.context.FSMContext, aiogram.fsm.storage.memory.MemoryStorage, aiogram.fsm.state.State and StatesGroup, aiogram.filters.Command and StateFilter, aiogram.types.FSInputFile for the InputFile(path) that sends the PDF, and aiogram.F for the text filters. There is no executor module in aiogram 3: the Dispatcher is built with storage= and no bot, and polling is its own run_polling method. FSMContext has clear, get_data and update_data and no finish or proxy, and ReplyKeyboardMarkup takes its rows in keyboard= and has no add. Each of the fifteen handlers in bot.py touches at least one of these, so the port is a rewrite of the decorators and the state calls, not of the logic that talks to the certificate API.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "This Telegram bot no longer starts: \"ImportError: cannot import name 'executor' from 'aiogram'\". List every aiogram import in the project with its file and line, and check each one against the aiogram release a fresh install of the requirements resolves, so the pull request names exactly which imports fail and which still work. Find by installing releases the first aiogram 3 release that lacks these names and the last aiogram 2 release that has them, and say which Python versions each of those two supports, including any aiohttp constraint. Then do two things: add a pin that makes the bot import again today on the Python version the project uses, and write the aiogram 3 port of every handler, state and keyboard, with a table of old name to new name that you verified by importing each new name. Prove the result by importing the bot module with a placeholder token and reporting how many handlers are registered. Do not contact Telegram. Open a pull request with the pin, the port, the table and the import check, and say which of the two you recommend merging first.",
"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 two parts the reviewer can take separately. The first is a one-line change to requirements.txt, aiogram<3, with a sentence stating that it holds on Python 3.11 and fails to install on 3.12 because of aiogram 2's aiohttp bound. The second is the ported bot.py: the imports rewritten to their aiogram 3 modules, the Dispatcher built without the bot, each decorator rewritten with Command, StateFilter and F filters, state.finish() and the state.proxy() blocks rewritten with clear, get_data and update_data, and run_polling in place of the executor. The description holds the import table, the two release boundaries with their dates, and the output of importing the module under each variant.
The reviewer reads the table against the diff: every old import in the list has a row, every row's new name is one the agent imported, and no handler lost its state filter in the rewrite, since a handler that used to run only in MyState.otp and now runs in any state is the kind of mistake a diff hides. The reviewer also decides the order: merge the pin today if the bot is down, then the port on its own branch, or the port alone if the bot's host already runs Python 3.12 and the pin cannot install there.
What the run does not prove is a conversation. Importing the module shows the handlers register and the code is consistent with aiogram 3; it does not send a message through Telegram, because the sandbox holds no bot token. The pull request says so, and the first /start after deploy is the reviewer's check.
Run it on every bot deploy that fails at import
A bot like this one has no test suite, so the error shows up in the host's deploy log or a crash loop. A deploy platform's failure notification usually cannot carry the Authorization: Bearer header a Rush webhook trigger needs, so a small handler on your server receives it and forwards the log text to the trigger's URL with the trigger's secret. The traceback lands after the saved prompt as event text, and the prompt tells the agent to start from the first failing import in it. Give the trigger's URL an Idempotency-Key header built from the deploy id, so a crash loop that reports the same failure every minute starts one run.
A bot with unpinned requirements can also be checked before anyone deploys. A schedule trigger on an automation in the Project can start one run a week that installs the requirements fresh and imports the bot module; a week in which every import resolves ends with no pull request, and the week aiogram moves ends with this one.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The import that fails depends on which aiogram a machine happens to hold. The laptop the bot was written on still has aiogram 2 and shows nothing wrong, and so does any environment that was never rebuilt. A Rush sandbox starts empty, resolves the requirements as a new host would, and hits the error on the first import. From there the agent installs 2.25.2, 3.0.0 and the current release in turn to find the boundary, and tries the pin on Python 3.11 and 3.12 to find where it stops working, with every command kept in the session.
A port across a major release is a list of small facts: which module each name moved to, which methods were renamed, which Python versions each side needs. Each fact is cheap to check by importing it and expensive to get wrong in a review. The pull request carries each check as the command and its output, so the reviewer confirms the table rather than reconstructing it.
Frequently asked questions
Which aiogram release removed executor?
aiogram 3.0.0, published 2023-09-01, has no aiogram.utils.executor, no aiogram.contrib and no FSMContext under aiogram.dispatcher. The last 2.x release is 2.25.2 from 2023-10-06. A requirements line that names aiogram with no bound resolves 3.x on every fresh install.
Can I just pin aiogram below 3?
Yes, on Python 3.11 or older. aiogram 2.25.2 requires aiohttp below 3.9.0, and aiohttp 3.8.6 fails to build on Python 3.12, so the pin stops working the day the host moves to 3.12. The pull request includes the pin for today and the port for after.
Why does my traceback mention reply_keyboard and not executor?
Because Python stops at the first import that fails, and in this bot that is aiogram.types.reply_keyboard on line 4, which aiogram 3 no longer has as a module. The executor import on line 8 would fail next. The agent checks every aiogram import on its own so the pull request lists all five that break, not only the first.
What replaces executor.start_polling in aiogram 3?
The dispatcher itself. In aiogram 3 the Dispatcher is created with storage= and no bot, and it has run_polling and start_polling methods that take the bot. The skip_updates argument the old call passed is not part of that call, and the port says what, if anything, replaces it.
Does the agent need my bot token?
No. The bot reads BOT_TOKEN from the environment, and the import check runs with a placeholder value, which is enough for the dispatcher to register its handlers. Nothing is sent to Telegram, and the first real message after deploy stays with you.
More jobs like this: Fix a bug from an alert
- Fix ImportError: Cannot Import Name 'json' From 'itsdangerous' in a Flask 1 App (itsdangerous)
- Fix "ImportError: cannot import name 'mock_s3' from 'moto'" in a pytest suite (moto)
- Fix "ImportError: cannot import name 'plot_confusion_matrix' from 'sklearn.metrics'" (scikit-learn)
- Fix "ImportError: cannot import name 'secure_filename' from 'werkzeug'" in a Flask-Uploads App (Flask-Uploads)
- Fix "ImportError: cannot import name 'simps' from 'scipy.integrate'" in SciPy 1.14 (SciPy)
- Fix "ImportError: cannot import name 'TextField' from 'wtforms'" in WTForms 3 (WTForms)