Skip to content

fix(knowledge): stop logging an oversized source file as an error - #35300

Merged
bolichen97 merged 1 commit into
mainfrom
fix/32635-oversized-ingest-double-log
Nov 12, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/32635-oversized-ingest-double-log

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Knowledge file over knowledge.max_ingest_file_mb that arrives as a single-file source, a web page, agent-fetched text or an artifact is reported once, as the pipeline's warning, instead of also filling the gateway log with an ERROR and a traceback.

Set knowledge.max_ingest_file_mb to 1 and add a 2 MB .md as a single-file Knowledge source. The pipeline logs a clear WARNING telling you to raise knowledge.max_ingest_file_mb, and then the sync task logs ERROR Background ingestion failed for ... with a FileTooLargeError traceback for the same file. A web-page source, text an agent fetched for a source, and an artifact over the cap do the same.

Why it matters

An ERROR with a traceback reads as a crash. Someone reading the gateway log, or a log monitor, sees a fault for a file Kiro Crew skipped on purpose and already explained, and the real errors in that log get harder to spot. The artifact pass runs on every gateway start, so one oversized artifact adds a fresh ERROR and traceback each time the gateway starts.

Not a goal

  • Changing what any path records for the file: the source row still ends error, the agent-text request still answers 500, and the artifact pass reports the same counts.
  • The dashboard upload. Its staged file is already capped at the same figure (the smaller of dashboard.upload_max_mb and knowledge.max_ingest_file_mb), so while that setting holds still it answers 413 before the pipeline can raise.
  • The agent-document route (POST /api/knowledge/agent-document). It has no handler of its own: the error reaches the web framework's generic 500, and giving it a proper answer is a separate change.
  • The Research Lab app's findings ingest, a built-in app site. It stays tracked in Five more knowledge ingest paths log an oversized file as an ERROR with a traceback #32635.

What changed (motivation → approach → change)

An oversized file on these five paths now leaves one WARNING in the log, not a WARNING plus an ERROR with a traceback.

Path Handler
Single-file source knowledge_sync.py _ingest_local_file_task
Web page knowledge_sync.py _background_url_sync
Agent-fetched text knowledge_ingest.py ingest_text
Artifacts, start-time and manual pass artifact_ingest.py reconcile_artifacts
Artifacts, change event artifact_ingest.py ArtifactKnowledgeSync._on_task_done

The pipeline's size check logs the WARNING and raises FileTooLargeError. Each of these callers catches every failure in one generic handler that logs it with a traceback, so the same skip was logged a second time as an ERROR.

Each handler now skips that log line when the error is a FileTooLargeError, the way #32507 did for the watched-folder scan. Nothing else moves: the same status is written, the same HTTP answer goes back, and every other failure still logs its ERROR with a traceback.

Two of those handlers import FileTooLargeError, so the handlers' facade, knowledge.py, lists it among its type-checking imports, as it does for every name they import.

Backwards compatibility

Compatible: only the log level for this one expected skip changes; every stored row, status, count and HTTP answer is the same.

Removes nothing: the change drops a duplicate log record and keeps every row, status, count and response.

Tests

Each test runs two failures and checks the recorded result is the same for both: a read error must still log an ERROR, and an oversized file must log none. So each fails if its fence is dropped, and also if it is widened (for example to RuntimeError, which FileTooLargeError subclasses).

  • test/test_knowledge_budget.py::TestBackgroundDeferralStaysRetryable::test_local_file_ingest_failure_ends_in_error: the single-file source ends error.
  • test/test_knowledge_handlers_coverage_source_writes.py::TestBackgroundAgentSync::test_ingest_failure_marks_source_error: the web-page source ends error.
  • test/test_knowledge_handlers_coverage_source_writes.py::TestIngestText::test_ingest_failure_is_500_and_cleans_up: agent text still answers 500 internal server error and removes its temp file.
  • test/test_knowledge_artifact_ingest.py::TestReconcile::test_a_failed_ingest_logs_an_error_unless_the_file_was_oversized and ::TestArtifactKnowledgeSync::test_a_failed_event_logs_an_error_unless_the_file_was_oversized: these run the real pipeline with the cap lowered to about 1 KB, so they also pin that the pipeline's own WARNING is logged and that the class it raises is the one the handlers skip.

Proof: PROVEN test/test_knowledge_artifact_ingest.py::TestReconcile::test_a_failed_ingest_logs_an_error_unless_the_file_was_oversized[oversized], test/test_knowledge_artifact_ingest.py::TestArtifactKnowledgeSync::test_a_failed_event_logs_an_error_unless_the_file_was_oversized[oversized], test/test_knowledge_budget.py::TestBackgroundDeferralStaysRetryable::test_local_file_ingest_failure_ends_in_error[oversized], test/test_knowledge_handlers_coverage_source_writes.py::TestIngestText::test_ingest_failure_is_500_and_cleans_up[oversized], test/test_knowledge_handlers_coverage_source_writes.py::TestBackgroundAgentSync::test_ingest_failure_marks_source_error[oversized] (head da9823e)

Determinism: the ten new cases passed 20/20 runs at -n0 and 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_knowledge_url_source.py. The five classes holding them passed in a shuffled class order (seed 7, 69 passed). A shuffled order of all three files (seed 32635) passed 168 of 175; the other 8 were Timeout >120s in fixture setup or teardown, never in a test body, while the shared host stalled on disk flushes (setup up to 947 s). Unshuffled, the three files pass whole (175 passed).

Manual verification

N/A — unit coverage sufficient: the handler tests drive the real sync tasks, the real ingest-text route and the real artifact pass over a real store, and the artifact tests hit the pipeline's real size check.

Screenshots / video

N/A — backend-only change; no frontend file is touched.

Related Issues

Part of #32635

The Research Lab findings site and the agent-document route stay open there.

Sibling sweep

Swept: git grep -n ".ingest_file(" -- src/kiro_crew, then each caller's exception handlers up to the first one that logs
Sibling: src/kiro_crew/dashboard/handlers/knowledge_sync.py -- changed here
Sibling: src/kiro_crew/dashboard/handlers/knowledge_ingest.py:140 -- changed here
Sibling: src/kiro_crew/knowledge/artifact_ingest.py -- changed here
Sibling: src/kiro_crew/knowledge/folder_watcher.py:1529 -- not affected -- already skips the log for FileTooLargeError (#32507)
Sibling: src/kiro_crew/knowledge/watcher.py:358 -- not affected -- catches FileTooLargeError before its generic handler
Sibling: src/kiro_crew/knowledge/sync.py:89 -- not affected -- ingests through ingest_text, which has no size check
Sibling: src/kiro_crew/dashboard/handlers/knowledge_agent_context.py:203 -- tracked in #32635
Sibling: src/kiro_crew/apps/builtins/auto_research/campaign/publication.py:584 -- tracked in #32635

Changed: knowledge_sync.py:350 (single-file source) and :652 (web page), knowledge_ingest.py:140 (agent text), artifact_ingest.py:913 (artifact pass) and :972 (artifact change event). Not affected: the upload handler at knowledge_ingest.py:379, whose staged file is capped at the same figure before the pipeline runs, so it answers 413 first unless the cap is lowered while the upload waits.

Pattern harvest

Rule candidate: review-prompt
Pattern: a generic except that logs with a traceback also catches a typed expected-skip error its raiser already logged as a WARNING, so one skip is logged twice, once as an ERROR; the sweep has to follow a re-raising caller up to the handler that logs.

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

Contribution License Agreement

Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of da9823e91d08d7764538ec6fddf4de493d90cf39 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. The fix is at mechanism level and covers each ingest_file caller that logs. The two callers left unfixed (agent-document route, Research Lab) are declared and tracked in #32635.

What this change ships

Inventory (6 items) — 6 justified

Intent: an oversized Knowledge file is reported once, as the pipeline's WARNING, with no extra ERROR and traceback. FIX.

  1. A single-file source over the cap no longer logs ERROR plus traceback; the row still ends error — justified
  2. A web-page source over the cap no longer logs ERROR plus traceback — justified
  3. Agent-fetched text over the cap still answers 500 but no longer logs ERROR — justified
  4. The artifact pass at startup or by hand no longer logs ERROR for an oversized artifact — justified
  5. The artifact change-event task no longer logs ERROR for an oversized artifact — justified
  6. The handler facade gains a type-checking import of FileTooLargeError — justified

[FIRST-PRINCIPLES-REVIEWED] da9823e

Description read

[DESCRIPTION-READ] 6d0d7811790c76a35b750634c7695cbaae96283848c15c14844cb70a1f406298

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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of da9823e91d08d7764538ec6fddf4de493d90cf39 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. This is a narrow change to log levels only. It suppresses logging only for the one type the pipeline raises right after its own WARNING, and it follows the fence #32507 already uses in folder_watcher.py.

Notes

  • This is the third and fourth copy of if not isinstance(exc, FileTooLargeError) at a catch site. Another option is to stop letting the pipeline's expected skip reach the generic handlers at all, for example by returning a skip status instead of raising. Any later caller of ingest_file will otherwise need the same fence again. That would be a separate follow-up, not this PR.

[DESIGN-REVIEWED] da9823e

Description read

[DESCRIPTION-READ] 56bdb6908a39ab617946bc5d865db970c990640e93ea4087df3c3c65e3d20856

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 Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed da9823e91d08d7764538ec6fddf4de493d90cf39 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] da9823e

Verdict parsed from the review's SHA-scoped output markers for commit da9823e91d08d7764538ec6fddf4de493d90cf39.

False positive or not applicable? A repository writer can comment:
/ai-review override fable da9823e91d08d7764538ec6fddf4de493d90cf39 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of da9823e91d08d7764538ec6fddf4de493d90cf39 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] da9823e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt da9823e91d08d7764538ec6fddf4de493d90cf39 false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 enabled auto-merge (squash) November 11, 2026 13:48
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 11, 2026
buluoray
buluoray previously approved these changes Nov 11, 2026

@buluoray buluoray 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.

Approve on 5aad911. An oversized Knowledge file now logs one WARNING (source id, size, limit only) instead of a WARNING plus an ERROR with a traceback. The dropped ERROR lines were the ones that carried the file path, URL or document name. Fences are exact-type and tested in both directions. Decisive lines: src/kiro_crew/knowledge/ingestion.py:902, src/kiro_crew/dashboard/handlers/knowledge_sync.py:350, src/kiro_crew/dashboard/handlers/knowledge_sync.py:651, src/kiro_crew/dashboard/handlers/knowledge_ingest.py:140, src/kiro_crew/knowledge/artifact_ingest.py:910, src/kiro_crew/knowledge/artifact_ingest.py:969

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Pushed d6aa3941f2ab to clear the red Backend Tests shards on 5aad9111b896: test/test_knowledge_handlers_facade.py::test_every_name_served_from_outside_the_family_is_visible_to_type_checkers failed because the two handler modules import FileTooLargeError and the facade's TYPE_CHECKING manifest did not name it. The only change against the approved head is that one manifest line in src/kiro_crew/dashboard/handlers/knowledge.py; the push dismissed the earlier approval, so this head needs a fresh one. The other red, test_the_scan_is_linear_not_quadratic, is the known timing flake recorded in #28212.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 11, 2026
A Knowledge file over knowledge.max_ingest_file_mb is an expected
skip: the ingestion pipeline logs it as a WARNING naming the config
key and raises FileTooLargeError. The single-file source sync, the
web-page sync, the agent ingest-text route and both artifact paths
(the start-time and manual pass, and the change event) caught that
in a generic handler and logged it again with a traceback, so one
skip read as an ERROR, on every gateway start for an oversized
artifact.

Each handler now skips that log line for FileTooLargeError and
records exactly what it did before: the same status, HTTP answer
and counts. Every other failure still logs its ERROR.

Part of #32635
@bolichen97
bolichen97 force-pushed the fix/32635-oversized-ingest-double-log branch from d6aa394 to da9823e Compare November 12, 2026 06:54
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_update_boot_apply.py and src/kiro_crew/dashboard/handlers/updates.py since this head's CI ran (ee7a026 -> fc196e4); CI re-running.

The red Backend Tests shards on d6aa3941f2ab (Linux 5 and 6, Windows 2 and 4, and the Coverage Gate that fails closed on them) were main's, not this change's: #35088 left test/test_wait_discipline_ratchet.py::test_the_scan_matches_known_sites and test/test_updates_handlers_facade.py::test_every_name_served_from_outside_the_family_is_visible_to_type_checkers red, and #35625 fixed both. This head carries that fix with the same one-commit patch (identical patch id). Analyze (python) failed on an API rate limit while uploading its results; the new run replaces it.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 6% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

This PR only changes logging. In the five handlers it lists, an oversized-file failure (knowledge.ingestion.FileTooLargeError) no longer logs a second time as an ERROR with a traceback. I checked the claims against the code:

  • The only place the knowledge module raises FileTooLargeError is ingestion.py:916, and it logs the WARNING just before that. So no case of this error loses its only log line.
  • Nothing else changes. The source row still ends error through _finalize_sync_status, cancels still re-raise, ingest_text still answers 500 and deletes its temp file, and the artifact counts are the same.
  • The skip only matches FileTooLargeError. Its parent class RuntimeError and every other failure still log an ERROR.
  • The logger names match the facade logger the tests check (kiro_crew.dashboard.handlers.knowledge).

Each change has a test that runs both a read error and an oversized file, so it would fail if a skip were dropped or widened. The two artifact tests also run the pipeline's real size check, which proves the pipeline's WARNING is logged and that the class it raises is the one the handlers skip.

The paths the PR leaves alone are declared and tracked in #3

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit da9823e91d · 149 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 12, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 12, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved. On this head the review checked that each of the five handlers skips its ERROR log only for the knowledge-ingest FileTooLargeError. That class is raised at one site, and that site already logs a WARNING and writes the SEL audit event. Every other path is unchanged: cancellation still re-raises, the import budget still answers 429, other failures still log ERROR, and status rows, the 500 answer and the counts stay byte-identical. A mutation run confirmed each test fails when its guard is removed and also when the guard is widened to RuntimeError.
Done well: every new test covers both a read error and an oversized file, and the artifact tests use the real pipeline size check instead of a mocked exception.
Optional:

  • For the two artifact paths (artifact_ingest.py:913 and :972), the removed ERROR line was the only log line that named the artifact slug. All artifacts share one source, so two oversized artifacts now leave two WARNINGs that differ only in size. A short info line naming the slug would bring that back. You could also change "Removes nothing" in the body to say the slug is now only in the SEL audit record.
  • The body says the three test files give 175 passed when run unshuffled. The review run gave 176, which matches the shuffled 168 + 8.

@bolichen97
bolichen97 merged commit ff1a93a into main Nov 12, 2026
101 of 102 checks passed
@bolichen97
bolichen97 deleted the fix/32635-oversized-ingest-double-log branch November 12, 2026 12:58
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants