python-telegram-bot/python-telegram-bot · warning · PTBUserWarning

`Application` instances should be built via the `Application

Error message

`Application` instances should be built via the `ApplicationBuilder`.

What it means

Application.__init__ warns when it is not instantiated from ApplicationBuilder, because manual construction easily produces misconfigured instances (missing job queue, persistence, updater wiring).

Source

Thrown at src/telegram/ext/_application.py:301

        updater: Updater | None,
        job_queue: JQ,
        update_processor: "BaseUpdateProcessor",
        persistence: BasePersistence[UD, CD, BD] | None,
        context_types: ContextTypes[CCT, UD, CD, BD],
        post_init: (
            Callable[["Application[BT, CCT, UD, CD, BD, JQ]"], Coroutine[Any, Any, None]] | None
        ),
        post_shutdown: (
            Callable[["Application[BT, CCT, UD, CD, BD, JQ]"], Coroutine[Any, Any, None]] | None
        ),
        post_stop: (
            Callable[["Application[BT, CCT, UD, CD, BD, JQ]"], Coroutine[Any, Any, None]] | None
        ),
    ):
        if not was_called_by(
            inspect.currentframe(), Path(__file__).parent.resolve() / "_applicationbuilder.py"
        ):
            warn(
                "`Application` instances should be built via the `ApplicationBuilder`.",
                stacklevel=2,
            )

        self.bot: BT = bot
        self.update_queue: asyncio.Queue[object] = update_queue
        self.context_types: ContextTypes[CCT, UD, CD, BD] = context_types
        self.updater: Updater | None = updater
        self.handlers: dict[int, list[BaseHandler[Any, CCT, Any]]] = {}
        self.error_handlers: dict[
            HandlerCallback[object, CCT, None], bool | DefaultValue[bool]
        ] = {}
        self.post_init: (
            Callable[[Application[BT, CCT, UD, CD, BD, JQ]], Coroutine[Any, Any, None]] | None
        ) = post_init
        self.post_shutdown: (
            Callable[[Application[BT, CCT, UD, CD, BD, JQ]], Coroutine[Any, Any, None]] | None
        ) = post_shutdown

View on GitHub (pinned to d3b69d2e9f)

Solutions

1. Use ApplicationBuilder().token(TOKEN).build()
2. For custom setups use ApplicationBuilder().bot(custom_bot).update_queue(q).build()

Example fix

# before
app = Application(bot=bot, update_queue=asyncio.Queue())

# after
app = ApplicationBuilder().token(TOKEN).build()

# always build via builder
from telegram.ext import ApplicationBuilder
app = ApplicationBuilder().token(TOKEN).build()

When it happens

Trigger: Calling Application(...) directly (e.g. Application(bot=bot, update_queue=queue)) instead of ApplicationBuilder().token(...).build().

Common situations: Porting old code from version 13's Application(...) or DI/test code constructing Application manually.

Related errors

• This Application was not initialized via `Application.initia
• Either contact or phone_number and first_name must be passed
• Either contact or phone_number and first_name must be passed
• `current_offset` and `next_offset` are mutually exclusive!
• Cannot {action} an inaccessible message

AI-assisted analysis of python-telegram-bot/python-telegram-bot@d3b69d2e9f (2026-08-28). Data as JSON: /api/errors/e1f13c85986518f2. Report an issue: GitHub.