troubleshooting

symptom-driven fixes for the telegram failures users hit most often in real bots.

error text → cause → fix

search this table for the exact wording Telegram (or Node) gave you:

bot does not start

import { createBot } from "yaebal";

const token = process.env.BOT_TOKEN;

if (!token) {
  throw new Error("BOT_TOKEN is missing");
}

const bot = createBot(token);

ERR_MODULE_NOT_FOUND / esm import errors

yaebal is "type": "module". Node's ESM resolver does not add extensions for you — a local import needs the .js specifier that the compiled output will actually have, even while editing the .ts source.

export const loadUser = async (id: number) => ({ id });

// @ts-expect-error — ERR_MODULE_NOT_FOUND at runtime: node's esm resolver
// does not add extensions for you, so this fails to resolve even though
// users.ts sits right next to this file.
import { loadUser } from "./users";

// ✅ write .js even though the source file is users.ts — nodenext rewrites
// nothing at compile time; this is what actually ends up on disk.
import { loadUser as loadUserFixed } from "./users.js";

await loadUserFixed(1);

polling receives no updates

telegram allows either long polling or webhooks for a token, not both. a common failure is 409 conflict: terminated by other getUpdates request: another process is polling the same token, or a webhook is still registered.

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

// if polling gets 409 conflict, make sure no webhook is set
await bot.api.call("deleteWebhook", { drop_pending_updates: true });

// then start exactly one polling process
await bot.start();

import { Bot } from "@yaebal/core";

const token = process.env.BOT_TOKEN!;

const bot = new Bot(token, {
  allowedUpdates: [
    "message",
    "callback_query",
    "chat_member",
    "message_reaction",
    "chat_join_request",
  ],
});

webhook does not fire

use getWebhookInfo first. telegram tells you the registered url, pending update count, and the last delivery error.

import { createBot } from "yaebal";
import type { WebhookInfo } from "@yaebal/types";

const bot = createBot(process.env.BOT_TOKEN!);

const info = await bot.api.call<WebhookInfo>("getWebhookInfo");
console.log(info.url, info.last_error_message);

see webhooks and @yaebal/web.

callback button spinner hangs

telegram clients show a loading spinner until the bot answers the callback query. answer it at the top of the handler, then edit or send messages.

import { InlineKeyboard, createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.command("start", (ctx) =>
  ctx.reply("deploy to production?", {
    reply_markup: new InlineKeyboard().text("confirm", "confirm:deploy").build(),
  }),
);

bot.callbackQuery(/^confirm:/, async (ctx) => {
  await ctx.answerCallbackQuery(); // answer first so the client spinner stops
  await ctx.reply("confirmed");
});

bot.start();

formatting is broken

media upload fails

use media.path for local files, media.buffer for in-memory bytes, media.url for public urls, and raw strings for telegram file_ids.

import { createBot, media } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.command("send", async (ctx) => {
  await ctx.sendPhoto(media.url("https://example.com/cat.jpg"));
  await ctx.sendDocument(media.path("./report.pdf"));
  await ctx.sendPhoto("AgACAgIAAx..."); // existing file_id also works
});

session or plugin fields are missing

in yaebal, plugin context fields exist downstream of the .install() call. install plugins before handlers that use them, and encode plugin dependencies in the plugin type when you write your own.

types look too weak

use createBot() from the yaebal meta package for rich generated runtime contexts. a bare new Bot(token) from @yaebal/core intentionally exposes the small base context unless you provide a custom context factory.

bot feels slow / updates pile up

sequential long polling processes one update at a time by design — a slow handler (a database call, an outbound http request) blocks everything behind it in the same chat and others besides.

still stuck

• search the generated bot api reference for the exact method.
• turn the failing behavior into a test with @yaebal/test.
• check production patterns in production.