langchain-ai/deepagents · error · ValueError

Telegram bot token is required (DEEPAGENTS_TALON_TELEGRAM_BO

Error message

Telegram bot token is required (DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN or TELEGRAM_BOT_TOKEN)

What it means

The Telegram channel factory `from_talon_config` requires a bot token to authenticate with the Telegram Bot API. It reads `DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN` or falls back to `TELEGRAM_BOT_TOKEN`; if neither env var is set (in the supplied env mapping), it raises `ValueError` before constructing the channel.

Source

Thrown at libs/talon/deepagents_talon/channels/telegram.py:141

        """Build Telegram channel configuration from Talon environment values.

        Args:
            config: Talon process configuration.

        Returns:
            Telegram channel configuration.

        Raises:
            ValueError: If the bot token is missing or exposure config is invalid.
        """
        env = config.env
        token = env.get("DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN") or env.get("TELEGRAM_BOT_TOKEN")
        if not token:
            msg = (
                "Telegram bot token is required "
                "(DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN or TELEGRAM_BOT_TOKEN)"
            )
            raise ValueError(msg)
        session = Path(
            env.get("DEEPAGENTS_TALON_TELEGRAM_SESSION_DIR", str(config.channel_dir / "telegram")),
        )
        inbound_media_dir = Path(
            env.get(
                "DEEPAGENTS_TALON_TELEGRAM_MEDIA_DIR",
                str(config.inbound_media_dir / "telegram"),
            ),
        )
        outbound_media_dir = outbound_media_root_from_env(env)
        exposure = channel_exposure_from_env(
            env,
            ChannelExposureEnv(
                provider="Telegram",
                env_prefix="DEEPAGENTS_TALON_TELEGRAM",
                open_ack=OPEN_EXPOSURE_ACK_ENV,
                require_self_operator=True,
            ),

View on GitHub (pinned to a1af029e6e)

Solutions

Export DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN with the token from @BotFather.
Or set the more generic TELEGRAM_BOT_TOKEN (e.g. if shared with other Telegram tooling).
Verify the variable is actually visible to the process (check your .env loading, systemd EnvironmentFile, or container env configuration).

Example fix

# before
export DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN=
# after
export DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN=123456:ABC-DEF_your_botfather_token

Defensive patterns

Strategy: validation

Validate before calling

import os
assert os.environ.get("DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN") or os.environ.get("TELEGRAM_BOT_TOKEN"), (
    "Telegram bot token missing"
)

Type guard

def has_telegram_token(env: dict[str, str]) -> bool:
    return bool(env.get("DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN") or env.get("TELEGRAM_BOT_TOKEN"))

Try / catch

try:
    channel = TelegramChannel.from_talon_config(config, env=os.environ)
except ValueError as exc:
    logging.error("Telegram channel not configured: %s", exc)
    raise SystemExit(1)

Prevention

Add the token to your .env / secret manager and load it before startup
Validate required env vars at process start with a fail-fast check
Use one canonical variable name per deployment to avoid fallback confusion
Check container/systemd env injection when migrating environments

When it happens

Trigger: Building the Telegram channel via `from_talon_config` when neither `DEEPAGENTS_TALON_TELEGRAM_BOT_TOKEN` nor `TELEGRAM_BOT_TOKEN` is present in the `env` mapping passed in.

Common situations: Fresh deployments where the token was never exported; running in systemd/containers where the env file wasn't loaded; typo'd variable names; tokens stored in a secrets manager but not injected into the process environment.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/ee6e8d1b5ff1e5e6. Report an issue: GitHub.