Skip to content

troubleshooting.md

Latest commit

 

History

History
191 lines (133 loc) · 6.49 KB

troubleshooting.md

File metadata and controls

191 lines (133 loc) · 6.49 KB
Raw

Troubleshooting

AddTelegramBot must be called before ...

Framework handler и transport APIs требуют Telegram bot services.

Правильный order:

builder.Services.AddTelegramBot(options => options.Token = token);
builder.Services.AddTelegramHandlersFromAssembly(typeof(Program).Assembly);
builder.Services.AddLongPolling();

Assembly does not contain generated Telegram handler metadata

AddTelegramHandlersFromAssembly(...) требует IWF.TeleFlow.Generators.

Исправление:

<PackageReference Include="IWF.TeleFlow.Generators" Version="..." PrivateAssets="all" />

Потом пересобери application.

Если generated registration не нужен, используй:

builder.Services.AddTelegramHandler<StartHandler>();

Или зарегистрируй module явно:

builder.Services.AddTelegramModule<AdminHandlers>();

Не переходи на deprecated reflection assembly registration как способ починить missing generated metadata.

TLF027: у handler нет route attribute

State и filter attributes ограничивают handler, но сами не route-ят updates.

Неправильно:

[State("registration:name")]
[HasText]
public Task Name(MessageContext ctx, CancellationToken ct)
{
    return Task.CompletedTask;
}

Правильно:

[Message]
[State("registration:name")]
[HasText]
public Task Name(MessageContext ctx, CancellationToken ct)
{
    return Task.CompletedTask;
}

Используй [Message], [Command], [Callback], [ChatMemberUpdated] или другой явный route attribute перед state и filter constraints.

Handler dependency was not registered

TeleFlow валидирует параметры handler methods до нормальной обработки updates. Если handler просит сервис, этот сервис должен быть зарегистрирован в DI:

public sealed class TicketHandler
{
    [CommandTemplate("ticket {id:long}")]
    public Task Ticket(
        MessageContext ctx,
        ITicketRepository tickets,
        CancellationToken ct)
    {
        // ...
    }
}

Зарегистрируй dependency до сборки приложения:

builder.Services.AddScoped<ITicketRepository, EfTicketRepository>();

То же правило действует для Telegram error handlers и custom filters.

Current update accessor падает вне обработки update

ITelegramCurrentUpdateAccessor scoped на один входящий Telegram update. Он работает внутри handlers, middleware и scoped services, до которых дошёл update pipeline.

Он не работает из application startup, background jobs, singleton services или кода, который выполняется до появления update.

Используй его из scoped services:

public sealed class UserService(ITelegramCurrentUpdateAccessor current)
{
    public long RequireUserId()
    {
        return current.User?.Id
            ?? throw new InvalidOperationException("Для этой операции нужен Telegram user.");
    }
}

Не внедряй его в singleton services.

Можно ли читать token из appsettings.json?

Да. TeleFlow не важно, откуда пришёл token. Прочитай его через обычную .NET configuration и явно передай resolved value:

builder.Services.AddTelegramBot(options =>
{
    options.Token = configuration["Telegram:BotToken"]
        ?? throw new InvalidOperationException("Telegram:BotToken is not configured.");
});

Смотри Конфигурация и секреты.

Handler не срабатывает

Проверь:

  • update type: message, callback, chat member;
  • command prefix;
  • text exact match vs contains;
  • state requirement;
  • class-level filters;
  • custom filter return value;
  • allowed updates for long polling.

State недоступен

Зарегистрируй state storage:

builder.Services.AddMemoryStateStorage();

Для custom storage убедись, что IStateStore и state middleware registered.

Wizard back не работает

Wizard back требует state history storage. AddMemoryStateStorage() его регистрирует. Custom storage должен предоставить IStateHistoryStore.

Callback data слишком длинная

Telegram callback data ограничен 64 UTF-8 bytes. Используй compact payloads:

[CallbackData("t")]
public sealed record TicketAction(long Id, string A);

Не клади large JSON payloads в callback data.

Callback data не смогла распаковаться

Если в логах есть Telegram callback data failed to deserialize, callback совпал с typed [Callback<TPayload>] route по compact prefix и количеству fields, но payload не удалось декодировать. Частые причины:

  • пользователь нажал старую inline-кнопку после изменения callback payload type;
  • numeric, boolean или enum field содержит invalid value;
  • другой компонент бота сгенерировал callback data с тем же prefix, но другим field format.

TeleFlow считает такой typed route не сматченным, поэтому raw callback fallback может ответить пользователю. Проектируй callback payloads так, чтобы они переживали версии: используй короткие стабильные prefixes, передавай IDs вместо больших объектов и заводи новый prefix, когда deployed callback shape меняется несовместимо.

Webhook возвращает unauthorized

Проверь SecretToken configuration и Telegram webhook settings. Incoming request должен использовать expected secret token.

Бот получает старые updates после рестарта

Telegram может вернуть pending updates после downtime. Current public API не документирует drop-pending-updates option. Deployment и startup behavior нужно проектировать с учётом pending updates.