# Fix "ImportError: cannot import name 'executor' from 'aiogram'" in a Telegram bot

Yes. An agent maps each aiogram 2 import in your bot to its aiogram 3 home or a pin, finds the release boundary, and proves the bot imports again.

[Run this on Rush](https://cloud.getrush.ai/run/fix-cannot-import-name-executor-from-aiogram/aiogram/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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](https://getrush.ai/run/fix-cannot-import-name-json-from-itsdangerous/itsdangerous/)
- [Fix "ImportError: cannot import name 'mock_s3' from 'moto'" in a pytest suite](https://getrush.ai/run/fix-cannot-import-name-mock-s3-from-moto/moto/)
- [Fix "ImportError: cannot import name 'plot_confusion_matrix' from 'sklearn.metrics'"](https://getrush.ai/run/fix-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](https://getrush.ai/run/fix-cannot-import-name-secure-filename-from-werkzeug/flask-uploads/)
- [Fix "ImportError: cannot import name 'simps' from 'scipy.integrate'" in SciPy 1.14](https://getrush.ai/run/fix-cannot-import-name-simps-from-scipy-integrate/scipy/)
- [Fix "ImportError: cannot import name 'TextField' from 'wtforms'" in WTForms 3](https://getrush.ai/run/fix-cannot-import-name-textfield-from-wtforms/wtforms/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
