Skip to content

fix(telegram): treat a non-JSON response body as a failed call - #18862

Merged
iamwhatever merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/telegram-non-json-error-body-is-a-failed-send
Oct 11, 2026
Merged

iamwhatever merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/telegram-non-json-error-body-is-a-failed-send

Conversation

@javenciu

@javenciu javenciu commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Telegram Bot API response whose body is not JSON (an HTML error page) is handled as a failed call, so a reply's fallbacks run and the answer still reaches the chat.

TelegramClient._api_request parses every response with resp.json(content_type=None). Telegram's edge, or a proxy the client supports (TELEGRAM_API_BASE_URL, HTTPS_PROXY), answers a 502 with an HTML page. aiohttp's json.loads raises JSONDecodeError for it, a ValueError. The except arm catches only aiohttp.ClientError and asyncio.TimeoutError, so the error escaped a call whose docstring says it "Returns the 'result' field or None on error".

On a reply, the first send happens on the renderer's live stream. The escape ran out of on_text_chunk before the seal, so the seal's fallback, which re-sends a final answer whose send failed "so the completed answer (and its keyboard) is never silently lost", never ran. The answer did not reach the chat.

Why it matters

One transient 502 from Telegram's edge or a proxy loses the turn's answer, and the user has to ask again. Every other failure of the same send (a timeout, a reset, a JSON error body) already returns None and takes the fallback.

Not a goal

  • _call_raw (the getMe token check) parses its body the same way and is not changed here; its callers handle a failed check separately.
  • A JSON body that is not an object (a bare list or string) is not changed here.
  • An empty body is unchanged: aiohttp returns None for it, which already takes the failure path, with no error code.
  • The duplicate a retried send can produce after a lost response is a separate, stated limit of the send-retry change; this change does not add sends.

What changed (motivation → approach → change)

  • Symptom: after a 502 HTML page on a reply's first send, the answer never reaches the chat.
  • Root cause: a body that is not JSON raised out of _api_request instead of taking its failure path.
  • Change, in src/kiro_crew/telegram/client.py, TelegramClient._api_request: resp.json() is wrapped in try/except ValueError. A body that does not parse becomes a failure body carrying the HTTP status as its error code ({"ok": False, "error_code": resp.status, "description": "response body is not JSON"}). The existing failure path then handles it as it handles a JSON error: it records the call's duration, fills err_out, logs a WARNING and returns None. A 429 page gets the same single wait and retry as a JSON 429.
  • Callers that now get None instead of an exception: every call through _api and _api_multipart. That is send_message, send_rich_message, send_message_draft, edit_message, edit_message_reply_markup, send_typing, answer_callback, delete_message, set_message_reaction, send_photo, send_document, send_voice, send_media_group, download_file, set_my_commands and _get_updates. None of them relied on the exception: grep -rn "JSONDecodeError\|except ValueError" src/kiro_crew/telegram finds only unrelated parse helpers (_url_is_loopback, _api_base, and three in session_resume.py, transport.py and dispatch/pickers.py). Two paths change in a visible way:
    • The polling loop: a non-JSON getUpdates response took the loop's catch-all ("Telegram polling unexpected error" with a traceback, then a fixed 5 s sleep). It now takes the loop's back-off for a rejected call, as a JSON error does.
    • send_rich_message latches rich rendering off for the process only on the Bot API's own answer: a JSON 4xx other than 400 and 429, which is how a server without the method answers every call. A page that is not JSON carries an edge's or a proxy's status, not the API's verdict, so _api_request adds body_is_json: False to err_out for it, and send_rich_message treats it as it treats a 5xx: rich stays on, and the 400 streak is not counted.

Rejected alternative:

  • Catching the error in the renderer: the escape reaches every caller of the client, and the client already documents None on error, so the fix belongs where the contract is stated.

Backwards compatibility

Compatible: only a response whose body is not JSON behaves differently. It returns None with its status in err_out, plus body_is_json: False, instead of raising. A JSON body, error or success, is handled exactly as before, and its err_out carries the same two keys as before.

Removes nothing: no field, parameter or function is removed.

Tests

test/test_telegram.py, new class TestNonJsonErrorBody, before TestClientHealth, on a fake session whose responses are parsed with json.loads as aiohttp parses them:

  • test_a_502_html_page_is_a_failed_call_with_its_status: _api returns None and err_out["error_code"] is 502.
  • test_send_message_returns_none_for_a_502_html_page.
  • test_the_answer_still_reaches_the_chat_after_a_502_html_page: the real TelegramRenderer over the real client; the first sendMessage gets the 502 page, and the answer still lands in a later sendMessage or editMessageText.
  • test_a_json_error_body_is_reported_as_before[400] and [502] (controls): err_out holds the body's own code and description.
  • test_a_successful_send_is_unchanged (control).
  • test_one_proxy_error_page_does_not_turn_rich_messages_off: the first sendRichMessage gets an HTML 403 page, and the next one still goes out as a rich message; _rich_unsupported stays False. Red on this branch's first version (which latched on that page): AssertionError: one non-JSON 403 page from a proxy turned sendRichMessage off for the process, 3 of 3 serial runs. The existing latch tests (a JSON 404 latches at once; persistent 400s latch) pass unchanged.

Red on origin/main 843abe3, with only the test file copied onto it, pytest test/test_telegram.py -k TestNonJsonErrorBody -p no:cacheprovider -n 0, 3 of 3 serial runs, the same failures each time: 4 failed, 3 passed (the controls):

FAILED test/test_telegram.py::TestNonJsonErrorBody::test_a_502_html_page_is_a_failed_call_with_its_status - json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
FAILED test/test_telegram.py::TestNonJsonErrorBody::test_send_message_returns_none_for_a_502_html_page - json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
FAILED test/test_telegram.py::TestNonJsonErrorBody::test_the_answer_still_reaches_the_chat_after_a_502_html_page - json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
FAILED test/test_telegram.py::TestNonJsonErrorBody::test_one_proxy_error_page_does_not_turn_rich_messages_off - json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
=========== 4 failed, 3 passed, 499 deselected, 2 warnings in 4.54s ============

The fourth test guards the latch, yet it fails on main for the same reason as the other three: main's _api lets the JSONDecodeError from the first HTML page escape from send_rich_message, so the test never reaches its latch assertion. Its own red is on this branch's first version, above.

Green on this branch (on origin/main 843abe3): test/test_telegram.py, 3 of 3 serial runs, 506 passed each. The 7 test files that import kiro_crew.telegram.client, test/test_telegram.py first, run serially: 1128 passed, exit 0. mypy src/kiro_crew/telegram/client.py: no issues. flake8, isort, black, scripts/check_black_formatting.py, scripts/check_comment_history.py (with COMMENT_HISTORY_BASE_REF=origin/main) and scripts/docs-lint.sh pass.

Manual verification

N/A — unit coverage sufficient: the tests drive the real _api_request, send_message and renderer, with only the HTTP session faked, and parse each body the way aiohttp does.

Related Issues

Open PRs that change src/kiro_crew/telegram/client.py or test/test_telegram.py were listed with gh pr list --repo kirodotdev/KiroCrew --state open --limit 1000 --json number,files (661 open PRs; for those whose file list stops at 100, the rest were read page by page from gh api repos/kirodotdev/KiroCrew/pulls/<n>/files): #6595, #7626, #15111, #15273, #17582 and #18215, all on test/test_telegram.py. Each patch was checked with git apply --check (exact context) against main and against this branch, with the same result on both (#7626 already fails on main).
GitHub search (gh search issues and gh search prs --repo kirodotdev/KiroCrew, open and merged) for "telegram JSONDecodeError 502", "telegram non-json response" and "telegram bad gateway" found nothing.

Pattern harvest

Rule candidate: review-prompt
Pattern: a client that documents "None on error" must catch the parse of the response body as well as the transport; an HTML error page from an edge or proxy is an ordinary response, and its decode error otherwise escapes every caller.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 10, 2026 13:19
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention labels Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision aa31abfc43a137516c47f846292a49de012cfecb touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of aa31abfc43a137516c47f846292a49de012cfecb via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] aa31abf

Description read

[DESCRIPTION-READ] 7329b2a0263c7eb63137ca6d06b0e66362374c174e856ff8f0895ee801ea649c

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of aa31abfc43a137516c47f846292a49de012cfecb via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check one thing before merge: the deleted coverage-baseline row is the ratchet's required removal, which means telegram/client.py now measures at or above the 80% floor.

Not justified as shipped

  • Item 4 — undeclared: the description never mentions deleting src/kiro_crew/telegram/client.py 61.8 # 306/495 from .github/coverage-baselines/backend.txt. scripts/check_per_file_coverage.py:32 requires removing a row once the file graduates, so this is a mandated rider.

What this change ships

Inventory (4 items) — 3 justified

Intent: when Telegram or a proxy returns an HTML error page, the reply's fallback still runs so the answer reaches the chat. This is a FIX.

  1. A non-JSON response (an HTML 502 page) now counts as a failed call carrying its HTTP status, so the reply fallback runs and the answer lands. — justified
  2. The polling loop now handles a non-JSON getUpdates page with the same back-off as a rejected call. Before, it went to the catch-all handler, which logged a traceback and slept 5 s. — justified
  3. A non-JSON 4xx page from a proxy no longer turns rich messages off for the whole process or counts toward the 400 streak. Without this, item 1 would newly cause that latch. — justified
  4. telegram/client.py is removed from the coverage baseline. — undeclared

[FIRST-PRINCIPLES-REVIEWED] aa31abf

Description read

[DESCRIPTION-READ] c2c9d1c779b3c366f34a208009f7e671facb56e72a32fcfeb8ccf200427ae0ab

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed aa31abfc43a137516c47f846292a49de012cfecb via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] aa31abf

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed aa31abfc43a137516c47f846292a49de012cfecb via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] aa31abf

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@javenciu

Copy link
Copy Markdown
Contributor Author

The second commit (6a03874) answers the Coverage Gate. The new tests take src/kiro_crew/telegram/client.py to 83.1% in CI, above the 80% per-file floor, so the gate asked for the file to leave .github/coverage-baselines/backend.txt. The change is the gate's own refresh (scripts/check_per_file_coverage.py --update-baseline) run against this PR's coverage-backend artifact from run 38055250822; it removed that one line and nothing else. Re-running the check against the same artifact with the refreshed baseline exits 0.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 10, 2026
_api_request parses every Bot API response with resp.json(). An HTML
error page, which Telegram's edge or a configured proxy returns for a
502, raised JSONDecodeError (a ValueError). The except arm catches only
aiohttp.ClientError and asyncio.TimeoutError, so the error escaped the
call that documents "Returns the 'result' field or None on error".

On a reply's first send the escape ran out of the renderer before its
seal, so the fallback that resends a failed final answer never ran and
the answer did not reach the chat.

A body that is not JSON is now a failed call like any other. Its HTTP
status stands in for the error code the body did not carry, so the
existing failure path records the duration, fills err_out, logs a
WARNING and returns None, and a 429 page gets the same single wait and
retry as a JSON 429. Callers get None instead of an exception and take
their failure paths. A JSON body, error or success, is handled as
before.
The new non-JSON body tests take src/kiro_crew/telegram/client.py to 83.1%
in CI, above the 80% per-file floor, so the Coverage Gate requires the file
to leave the baseline. This is the gate's own refresh
(`check_per_file_coverage.py --update-baseline`) run against this PR's CI
coverage artifact; it removed only that line.
@javenciu
javenciu force-pushed the fix/telegram-non-json-error-body-is-a-failed-send branch from 6a03874 to aa31abf Compare October 11, 2026 08:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 11, 2026

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before this PR, an HTML error page from Telegram's edge or a proxy raised JSONDecodeError out of _api_request, so the renderer's seal fallback never ran and the answer was lost. The PR catches ValueError around resp.json() and turns it into a failure body that carries the HTTP status. That fixes it where the client's "None on error" contract is stated. I read the whole _api_request. UnicodeDecodeError is also a ValueError, so it is caught too. A 429 page gets the same single bounded retry as before. A 200 HTML page is still a failure. JSON bodies, error or success, follow the same path as before. send_rich_message checks the new body_is_json flag, so one proxy 4xx page neither latches rich rendering off nor counts toward the 400 streak. I grepped for other err_out readers, and that is the only one that branches on the code. The tests drive the real client and renderer, with only the HTTP session faked, and the description shows them red on main. Dropping the telegram/client.py row from the coverage baseline is the ratchet's required removal once the file graduates. Checks are green, and the GPT, Opus, Design and First Principles lanes pass. — crew-pr-reviewer (deep re-check)

@iamwhatever
iamwhatever enabled auto-merge (squash) October 11, 2026 17:35
@iamwhatever
iamwhatever merged commit 4ed523c into kirodotdev:main Oct 11, 2026
104 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants