Practical diagnostics
KFA Agent Troubleshooting Field Guide — Practical Diagnostics from Unresolved Problems
These 30 cards turn public incident research into safe starting points. The linked KFA Problems and primary reports describe specific environments; the checks below are proposed diagnostics, not claims that KFA reproduced or fixed the incidents. Prefer isolated test environments and synthetic data. A source-reported success is not an independent reproduction. An upstream proposal or merged change does not by itself prove release inclusion.
Six cards link canonical KFA Solutions, including four published in this research session and two that existed previously. All cards are editorial research, not Outcomes. No Problem is marked resolved by this guide. Confirm versions, platform and current upstream status before applying a change.
Copilot CLI ACP ignores sandbox settings
Problem: In ACP mode the write succeeds (exit 0) and the sandbox is not applied; the same policy and prompt in -p mode are blocked by the OS sandbox.
Affected environment: ACP mode sandbox application; 1.0.94-5 (reported; Windows 11 x64, PowerShell 7, custom .NET ACP client)
What we know: In ACP mode the write succeeds (exit 0) and the sandbox is not applied; the same policy and prompt in -p mode are blocked by the OS sandbox. This is an external report; KFA did not reproduce it.
Possible causes: A difference in the ACP execution path may prevent sandbox settings from being applied; the precise path is not confirmed here.
Check this first: Check the version and whether the client starts ACP or prompt mode.
Diagnostic procedure: In an isolated disposable environment, configure a harmless test file as read-only, run the same synthetic write through ACP and prompt mode, and record whether each is blocked. Do not include real secrets.
How to interpret the result: A write that succeeds only in ACP supports a mode-specific enforcement gap; a failure in both does not establish the report.
Potential fixes and workarounds: Release 1.0.103 says ACP honors sandbox settings; evaluate it under your change policy and repeat the isolated enforcement check.
What not to do: Do not rely on a configuration flag alone as a security boundary or test against valuable files.
Upstream status: The 1.0.103 release note reports ACP sandbox handling; exact correspondence to every reported environment is not independently verified.
Verification: Compare denial and exit status after the change; verify expected allow and deny cases.
Remaining unknowns: Which releases and ACP client configurations exhibit the same enforcement failure?
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Mastra Upstash logging buffer grows during an outage
Problem: logBuffer grows without bound during a sustained outage, and overlapping unawaited flush requests accumulate (one per write once the buffer is at or above batchSize).
Affected environment: UpstashTransport (packages/loggers/src/upstash/index.ts); current main at time of report (commit 4d0056f3 per triage comment); Node.js 24
What we know: logBuffer grows without bound during a sustained outage, and overlapping unawaited flush requests accumulate (one per write once the buffer is at or above batchSize). This is an external report; KFA did not reproduce it.
Possible causes: The report attributes growth to buffering and overlapping flushes while the endpoint rejects writes; verify the installed version.
Check this first: Confirm use of UpstashTransport and capture the installed logger version without recording log contents.
Diagnostic procedure: In a disposable test, simulate an unavailable log endpoint; observe queue length, memory and concurrent flush requests over a fixed interval. Restore connectivity and observe whether the queue drains.
How to interpret the result: A rising queue and overlapping requests during failure supports the reported mechanism; bounded queue size with recovery suggests a different bottleneck.
Potential fixes and workarounds: Assess @mastra/loggers 1.3.6 under your compatibility policy and test the bounded-buffer behavior. A bounded queue can drop older log records, so review the loss policy.
What not to do: Do not intentionally disrupt production telemetry or discard audit logs to run this test.
Upstream status: The project release notes list the bounded-buffer change in @mastra/loggers 1.3.6; oldest buffered records may be dropped when the buffer is full. No independent execution was performed here.
Verification: Under the same controlled outage, record whether memory and in-flight requests stay bounded and whether recovery resumes.
Remaining unknowns: Does the deployed package contain the change and what log-loss behavior is acceptable?
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
LiteLLM OAuth credential name lost on a Responses bridge
Problem: Proxy returns 400 saying per_user_oauth requires litellm_credential_name, although the deployment sets litellm_credential_name. Chat-mode Copilot models and direct /v1/responses calls reportedly work with the same credential.
Affected environment: GitHub Copilot per-user OAuth via chat-to-Responses bridge; v1.106.0 (built from main at 7ff5010674); reporter says same code on main at 906f927b23
What we know: Proxy returns 400 saying per_user_oauth requires litellm_credential_name, although the deployment sets litellm_credential_name. Chat-mode Copilot models and direct /v1/responses calls reportedly work with the same credential. This is an external report; KFA did not reproduce it.
Possible causes: The reporter suspects the chat-to-Responses bridge fails to carry the credential name; this is not confirmed.
Check this first: Check model routing mode and whether the named credential is configured, without printing its value.
Diagnostic procedure: With a test identity, compare the same sanitized request through the chat-to-Responses route and a direct Responses route; record status, model route, and whether a credential name is present as a boolean.
How to interpret the result: If direct Responses and chat mode work while the bridge reports a missing credential name, investigate bridge propagation; failures on all routes suggest a broader configuration issue.
Potential fixes and workarounds: The source does not establish a workaround. Compare the installed version and route configuration, and gather a minimal redacted reproduction for maintainers.
What not to do: Do not paste OAuth tokens or rotate production credentials merely to diagnose this mismatch.
Upstream status: The linked public report describes the behavior; no verified released fix is established here.
Verification: The affected bridge should return a comparable successful result for the same authorized test identity without exposing credentials.
Remaining unknowns: Whether other versions or database-backed deployments are affected.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
CrewAI system message becomes None or a list representation
Problem: OpenAI o1 path sends literal 'System: None' or a Python list repr as a user message; Anthropic path appends 'None' to the system string and, with a list first system message, yields a mixed list of a content block and bare strings
Affected environment: OpenAICompletion._format_messages and AnthropicCompletion._format_messages_for_anthropic; main @ 6b93fa0 (reported as 1.15.27), Python 3.12; formatting system messages whose content is None or a list of content parts
What we know: OpenAI o1 path sends literal 'System: None' or a Python list repr as a user message; Anthropic path appends 'None' to the system string and, with a list first system message, yields a mixed list of a content block and bare strings This is an external report; KFA did not reproduce it.
Possible causes: The reporter attributes the output to formatting code converting null or structured content into text; verify in a synthetic case.
Check this first: Check whether the affected system-message content is null, plain text or structured parts.
Diagnostic procedure: Use synthetic message content and capture only the formatted message shape before provider submission; compare the OpenAI o1 and Anthropic formatting paths if both are relevant.
How to interpret the result: Literal None or a Python-style list in the formatted prompt matches the report; valid structured blocks point to another stage.
Potential fixes and workarounds: Normalize synthetic input only after confirming the provider and SDK contract; treat that as a test hypothesis, not a proven workaround.
What not to do: Do not log real system prompts or assume a list can safely be converted to a string.
Upstream status: The upstream issue is a reporter observation; no fixed release is established in this review.
Verification: Re-run with null, text and list-shaped test cases and compare the formatted structure.
Remaining unknowns: The intended behavior for every structured block and affected release range.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
python-genai curated history retains half a user turn
Problem: Curated history keeps the first user Content and drops the later one (e.g. the function response), leaving a partial user turn with no model answer.
Affected environment: chats._extract_curated_history / chats.create(history=...); Reported at commit 618f0aa and google-genai 2.29.0 from PyPI (CPython 3.12.3, Linux x86_64); other versions unknown
What we know: Curated history keeps the first user Content and drops the later one (e.g. the function response), leaving a partial user turn with no model answer. This is an external report; KFA did not reproduce it.
Possible causes: The reporter attributes the partial turn to history curation after an invalid model entry; expected behavior is not established.
Check this first: Check the installed google-genai version and whether consecutive user Content entries precede an invalid model entry.
Diagnostic procedure: Build a synthetic history with two user entries followed by a model entry with empty parts; compare curated and uncurated history using the public chat history interface.
How to interpret the result: A retained first user entry with a missing later entry matches the report; other history differences need separate investigation.
Potential fixes and workarounds: Preserve the original test history and examine the application’s turn boundaries; no source-backed automatic rewrite is established.
What not to do: Do not remove or rewrite production conversation history as an unverified repair.
Upstream status: Reported against google-genai 2.29.0; the report does not establish a released fix.
Verification: The same synthetic turn should be represented consistently before and after a candidate change.
Remaining unknowns: Intended grouping behavior and the effect of intervening function calls.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
LangChain tool validation failure has no tool callbacks
Problem: No handleToolStart or handleToolError callback fires when schema validation fails; the failed tool call is absent from LangSmith traces.
Affected environment: @langchain/core StructuredTool.call; @langchain/core 1.2.17 and main aa1b519 (as reported); langchain 1.5.15, zod 4.6.5, Node.js 22.22, macOS
What we know: No handleToolStart or handleToolError callback fires when schema validation fails; the failed tool call is absent from LangSmith traces. This is an external report; KFA did not reproduce it.
Possible causes: Schema validation may fail before the tool-start/error callback path; this is reported behavior, not a confirmed general rule.
Check this first: Check whether input fails the tool schema before the tool body runs.
Diagnostic procedure: Using a synthetic tool and callbacks, compare one valid invocation with one invalid input; record the caller-visible exception and whether start/error callbacks fire.
How to interpret the result: If only invalid input lacks both callbacks while the caller gets a validation error, it matches the reported pre-execution gap; if valid calls also lack callbacks, inspect callback attachment.
Potential fixes and workarounds: Handle or record validation failures at the caller boundary while testing; this is a diagnostic design choice, not a reported upstream fix.
What not to do: Do not infer that a missing trace proves the tool was executed or silently succeeded.
Upstream status: Reported with @langchain/core 1.2.17; no released fix is established here.
Verification: Confirm both valid and invalid invocations have a visible, appropriately classified result in the application.
Remaining unknowns: Whether later SDK versions change callback behavior.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
MCP Go server accepts an unexpected legacy client
KFA Problem · Canonical KFA Solution
Problem: Server returns HTTP 200 and serves initialize, tools/list and tools/call instead of rejecting the legacy client with UnsupportedProtocolVersion (-32022, HTTP 400).
Affected environment: mcp server version negotiation and dispatch (initialize handler, negotiatedVersion, validateRequestMeta legacy path); v1.8.0 (as reported); Go go1.23+
What we know: Server returns HTTP 200 and serves initialize, tools/list and tools/call instead of rejecting the legacy client with UnsupportedProtocolVersion (-32022, HTTP 400). This is an external report; KFA did not reproduce it.
Possible causes: The reporter suspects a legacy dispatch path bypasses the configured supported-version restriction.
Check this first: Check the configured supported protocol versions and the client’s actual initialize request.
Diagnostic procedure: In a test server, compare a synthetic legacy client with a client sending the configured version; record the negotiated initialize result and separately test a harmless non-initialize request, capturing only protocol version, HTTP status and JSON-RPC error code.
How to interpret the result: A legacy initialize that succeeds on a server configured for 2026-only matches the report; an explicit version rejection points elsewhere.
Potential fixes and workarounds: Use the actual negotiated response and current official specification to assess compatibility; no verified released fix is asserted.
What not to do: Do not expose request tokens or enable an unsupported protocol version merely to silence the error.
Upstream status: The issue was closed by a merged change for legacy-format non-initialize requests. The implementation leaves initialize allowed; release inclusion remains unverified here.
Verification: Repeat the initialize and harmless non-initialize requests and verify the behavior appropriate to the installed version and configured server policy; do not assume initialize must be rejected by that change.
Remaining unknowns: Whether the installed SDK or specification revision changes legacy fallback behavior.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
MCP resource retry returns stale cached content
KFA Problem · Canonical KFA Solution
Problem: The retry result is cached under the plain URI, so a second read is served from cache without re-asking the user. With the middleware disabled, a manual retry carrying InputResponses and RequestState is answered from cache with the stale interim input_required result.
Affected environment: mcp ClientSession.ReadResource per-URI cache and multi round-trip (SEP-2322) middleware; v1.8.0 (3f3b699) and main 3c08147 as reported; Go go1.27.1 darwin/arm64
What we know: The retry result is cached under the plain URI, so a second read is served from cache without re-asking the user. With the middleware disabled, a manual retry carrying InputResponses and RequestState is answered from cache with the stale interim input_required result. This is an external report; KFA did not reproduce it.
Possible causes: A per-URI cache may reuse a result without accounting for retry input; the server may also need separate investigation.
Check this first: Check whether the failing resource read includes an input-required retry and whether URI caching is active.
Diagnostic procedure: In a controlled client, read a synthetic resource twice with different retry input and compare the returned result and server request count; compare with caching disabled only in that test.
How to interpret the result: A second read without a server request suggests a cache hit; a new server request with the wrong result requires server-side investigation.
Potential fixes and workarounds: The merged upstream change is a candidate to inspect; verify release inclusion separately before considering an upgrade.
What not to do: Do not disable production caching globally or assume a merged PR is included in a release.
Upstream status: The report targets Go SDK 1.8.0; PR 1371 was reported merged, with release inclusion unverified.
Verification: Confirm retries with distinct input reach the server and do not receive stale intermediate data.
Remaining unknowns: Which released SDK version contains the change and behavior under the actual middleware.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
AI SDK loses tool-result provider metadata
Problem: The role:tool result part gets providerOptions from the call metadata; distinct result metadata is lost. The assistant tool-call part correctly keeps call metadata.
Affected environment: packages/ai ui convert-to-model-messages; ai 7.0.137 (reported); upstream commit ba05943b69ad070558bb5bc912da99ec66d7d263 (reported)
What we know: The role:tool result part gets providerOptions from the call metadata; distinct result metadata is lost. The assistant tool-call part correctly keeps call metadata. This is an external report; KFA did not reproduce it.
Possible causes: The reported conversion appears to replace result metadata with call metadata; confirm with distinct markers.
Check this first: Check whether call metadata and tool-result metadata were deliberately different.
Diagnostic procedure: Create a synthetic tool result with distinct non-sensitive marker values in each metadata field; compare the message before and after conversion to model messages.
How to interpret the result: If the tool result carries the call marker after conversion, the report’s mismatch is present; identical markers cannot distinguish the paths.
Potential fixes and workarounds: Keep the original synthetic message for comparison and inspect the SDK version; no supported production workaround is established.
What not to do: Do not record real provider options or assume all metadata is safe to disclose.
Upstream status: Reported for ai 7.0.137; root cause and released fix remain unconfirmed here.
Verification: After a candidate change, verify call and result markers remain distinct through the round trip.
Remaining unknowns: Effects in different providers and later SDK releases.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
AI SDK final tool output remains preliminary
Problem: The part gets the final output value but keeps preliminary: true, so lastAssistantMessageIsCompleteWithToolCalls() returns false and sendAutomaticallyWhen-style continuation does not fire.
Affected environment: packages/ai ui chat addToolOutput / lastAssistantMessageIsCompleteWithToolCalls; ai 7.0.137 (reported); upstream commit ba05943b69ad070558bb5bc912da99ec66d7d263 (reported)
What we know: The part gets the final output value but keeps preliminary: true, so lastAssistantMessageIsCompleteWithToolCalls() returns false and sendAutomaticallyWhen-style continuation does not fire. This is an external report; KFA did not reproduce it.
Possible causes: The reported state update may preserve the preliminary flag after final output.
Check this first: Check the tool part’s preliminary flag after the final output is added.
Diagnostic procedure: In a synthetic chat state, add a preliminary output, then a final output for the same call; inspect the flag and the completion predicate before and after.
How to interpret the result: A final value with preliminary still true and a false completion predicate matches the report; a changed call identifier suggests a separate state issue.
Potential fixes and workarounds: Compare the installed version with the upstream issue and proposed change; do not assume an open proposal is available in a release.
What not to do: Do not force automatic continuation in production while tool state is uncertain.
Upstream status: Reported for ai 7.0.137; upstream proposal status and release inclusion require current verification.
Verification: A final result should clear the preliminary state and allow the application’s normal completion check.
Remaining unknowns: Framework-specific behavior and the first version containing any change.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
LiteLLM telemetry omits tool-call output details
Problem: Span attribute gen_ai.output.messages shows assistant message with empty parts and finish_reason tool_calls, so tool name, id and arguments are absent. For a streamed response delivering the tool call and finish_reason tool_calls in one chunk, span records finish_reasons ["stop"] while the application sees tool_calls.
Affected environment: litellm/integrations/opentelemetry.py (_transform_messages_to_otel_semantic_conventions, _transform_choices_to_otel_semantic_conventions); Reported on v1.104.2 (described as latest release); reporter says code path unchanged on main at 7ff5010. Other versions unknown.
What we know: Span attribute gen_ai.output.messages shows assistant message with empty parts and finish_reason tool_calls, so tool name, id and arguments are absent. For a streamed response delivering the tool call and finish_reason tool_calls in one chunk, span records finish_reasons ["stop"] while the application sees tool_calls. This is an external report; KFA did not reproduce it.
Possible causes: The reporter suspects tool-call serialization and streamed finish-reason handling in telemetry transformation.
Check this first: Check whether the application received a tool call while the exported span contains an empty output-parts array.
Diagnostic procedure: With mocked transport and synthetic tool arguments, compare streamed and non-streamed responses to the corresponding OpenTelemetry span attributes and finish reason.
How to interpret the result: Correct application output with missing span details suggests an instrumentation mismatch; missing calls in both paths suggests an upstream response problem.
Potential fixes and workarounds: Use application-side synthetic observations to triangulate the trace; no source-backed fix is established.
What not to do: Do not export real tool arguments, prompts, or secrets to shared logs.
Upstream status: Reported on LiteLLM 1.104.2 using mocked transport; no released fix established here.
Verification: Compare sanitized spans and application results for both streaming modes after a candidate change.
Remaining unknowns: Whether other versions or providers show the same attribute transformation.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
CrewAI deploy and run interpret env files differently
Problem: Per the reporter, deploy sends env values differently from crewai run: quotes are retained, inline comments end up in values, export-prefixed lines become keys named 'export KEY', and one line without '=' causes no env vars to be sent.
Affected environment: deploy env parsing (fetch_and_json_env_file in lib/cli/src/crewai_cli/utils.py); 1.15.23 (main), as reported; other versions unknown
What we know: Per the reporter, deploy sends env values differently from crewai run: quotes are retained, inline comments end up in values, export-prefixed lines become keys named 'export KEY', and one line without '=' causes no env vars to be sent. This is an external report; KFA did not reproduce it.
Possible causes: The reporter suspects the deploy parser treats quoting and line prefixes differently from the run path.
Check this first: Check the installed CrewAI version and which command parses the env file.
Diagnostic procedure: In a disposable project, use only synthetic placeholder values and compare the names and parsed representations of a quoted value, inline comment and export-prefixed line between run and deploy paths.
How to interpret the result: A mismatch only in deploy parsing supports the reported path difference; identical parsing suggests another configuration layer.
Potential fixes and workarounds: Review the relevant parser behavior before changing formatting; no general production rewrite or released fix is established.
What not to do: Never print real env values or deploy actual credentials as a diagnostic.
Upstream status: Reported on CrewAI 1.15.23; the linked proposed change was open in the prior review.
Verification: Repeat the synthetic comparison and confirm equivalent values reach both test paths.
Remaining unknowns: Behavior in other versions and whether a later release changed the parser.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
CrewAI flow returns None without a start method
Problem: Per the report, kickoff() prints a completion message and returns None, with state unchanged and method_outputs empty, rather than failing fast.
Affected environment: Flow; crewai 1.15.22 on Python 3.13 (as reported by issue author; other versions unknown)
What we know: Per the report, kickoff() prints a completion message and returns None, with state unchanged and method_outputs empty, rather than failing fast. This is an external report; KFA did not reproduce it.
Possible causes: A flow without an entrypoint may have no event that starts its listeners; check the actual flow definition.
Check this first: Check whether the flow has a declared start entrypoint and whether the observed listeners depend on it.
Diagnostic procedure: In an isolated synthetic flow, compare kickoff behavior with only listener methods and with an explicitly declared start method; inspect returned value and state transitions.
How to interpret the result: If the listener-only flow returns None and never changes state while the start-enabled example runs, this narrows the issue to entrypoint setup.
Potential fixes and workarounds: Follow the documented flow entrypoint pattern where appropriate; confirm the actual application’s intended event flow before editing.
What not to do: Do not assume None proves a successful workflow or add a start method blindly to production.
Upstream status: Reported on CrewAI 1.15.22; the prior proposed validator was closed without merge.
Verification: The expected start and listener actions should run and produce the expected test state.
Remaining unknowns: Whether later versions warn or change the entrypoint behavior.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
vLLM required tool choice returns only one parallel call
Problem: With required, only the first tool call is returned (finish_reason tool_calls) while auto returns 2 or 3 calls. Streaming and non-streaming behave the same. Single-call required and named tool choice work.
Affected environment: vllm/tool_parsers/structural_tag_registry.py (get_hermes_structural_tag), Hermes tool grammar; Rust frontend Hermes builder; vLLM main c23ca06b6d (0.31.1rc1.dev150), xgrammar 0.2.8
What we know: With required, only the first tool call is returned (finish_reason tool_calls) while auto returns 2 or 3 calls. Streaming and non-streaming behave the same. Single-call required and named tool choice work. This is an external report; KFA did not reproduce it.
Possible causes: The reporter suspects the Hermes structural grammar admits only one required tool call; sampling is an alternative explanation.
Check this first: Check whether Hermes parsing and tool_choice required are active and whether multiple tool calls are expected.
Diagnostic procedure: With synthetic tools and identical generation settings, compare required, auto and single named-tool requests; count calls and inspect finish reason in streaming and non-streaming responses.
How to interpret the result: If only required mode truncates multiple calls while named single calls work, the observed mode-specific behavior matches the report; sampling may still influence auto results.
Potential fixes and workarounds: Investigate the parser and version with maintainers; auto is a comparison, not a proven substitute with equivalent guarantees.
What not to do: Do not assume missing calls ran or change production tool-selection policy without review.
Upstream status: Reported on a 0.31.1 development build; PR 60770 was open in prior review and is not a released fix.
Verification: Verify the intended number of calls and their arguments under the selected policy in a controlled test.
Remaining unknowns: Affected models, sampling settings, and release inclusion of any fix.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
vLLM encoder-cache miss creates empty directories
KFA Problem · Canonical KFA Solution
Problem: Each cache-miss lookup leaves an empty <mm_hash>/ directory without encoder_cache.safetensors in the shared EC storage root
Affected environment: ECExampleConnector (encoder cache example connector); v0.30.0 per reporter; reporter says same code on main
What we know: Each cache-miss lookup leaves an empty <mm_hash>/ directory without encoder_cache.safetensors in the shared EC storage root This is an external report; KFA did not reproduce it.
Possible causes: The reported existence-check path may create a directory as a side effect on a cache miss.
Check this first: Check whether the EC example connector is in use and whether a cache lookup is a miss.
Diagnostic procedure: Use a dedicated temporary cache root with no user data; compare its directory listing before and after a synthetic miss, and inspect whether a cache artifact was written.
How to interpret the result: New empty hash directories after a miss match the reporter’s observation; their presence alone does not establish unbounded growth or an outage.
Potential fixes and workarounds: Review the merged upstream change and inspect the source of the installed build; the prior check found v0.32.0 still lacked the relevant behavior.
What not to do: Do not delete shared storage or user cache directories as a diagnostic.
Upstream status: PR 60826 was reported merged; inclusion in the examined v0.32.0 source was not verified.
Verification: A repeated synthetic miss should not create an empty directory if the candidate behavior is present.
Remaining unknowns: Which released build contains the fix and the real operational impact.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
ADK lower-is-better metric is marked failed
KFA Problem · Canonical KFA Solution
Problem: Evaluator PASSED is marked FAILED for lower-is-better score in the reported version.
Affected environment: google-adk 2.11.0, Python 3.11, Windows 11, reported.
What we know: Evaluator PASSED is marked FAILED for lower-is-better score in the reported version. This is an external report; KFA did not reproduce it.
Possible causes: The earlier aggregator assumed higher scores were better; the released implementation infers direction from individual statuses, subject to fallback.
Check this first: Check the installed ADK version, metric threshold and the per-invocation evaluator status.
Diagnostic procedure: Use a synthetic lower-is-better metric with one score below and one above its threshold; compare each status and the aggregate result without sending real evaluation data.
How to interpret the result: If an explicitly passing lower score becomes an aggregate failure, the direction mismatch is consistent with the report; mixed or threshold-equal cases need separate attention.
Potential fixes and workarounds: Assess ADK 2.13.0 under compatibility controls: its release lists a related change, and the reviewed implementation infers direction before comparing the mean.
What not to do: Do not label a gating metric INFORMATIONAL merely to conceal a failure.
Upstream status: The issue author reports before/after success; the PR page and issue comment disagreed on PR status, so cite the released change separately and do not assert PR merge.
Verification: Confirm expected pass and fail results, including threshold-equal and mixed cases, in the application.
Remaining unknowns: Ambiguous or conflicting direction defaults and effects on custom evaluators must be checked locally.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
HTTPX 0.28 rejects the proxies keyword
KFA Problem · Canonical KFA Solution
Problem: TypeError: Client.__init__() got an unexpected keyword argument 'proxies' after an HTTPX upgrade.
Affected environment: HTTPX 0.28.0; Python client library passing the removed proxies argument; The particular SDK and version must be checked locally
What we know: HTTPX 0.28.0 release notes state that the deprecated proxies parameter was removed. Discussion participants reported mixed results from pinning 0.27.2.
Possible causes: An older third-party SDK may still pass the removed argument; the traceback is needed to identify the actual caller.
Check this first: Inspect the traceback and installed HTTPX and client SDK versions in the affected environment.
Diagnostic procedure: Identify the constructor receiving proxies and the package that supplies it. In an isolated environment, compare the application under the existing dependency lock with a compatibility-tested client or a temporary HTTPX 0.27.2 pin.
How to interpret the result: A traceback from the SDK into an HTTPX constructor with proxies supports this compatibility mismatch. A different call path or persistent failure after a test pin requires further investigation.
Potential fixes and workarounds: Check the relevant client’s compatibility guidance and assess an SDK upgrade. One user reported success with HTTPX 0.27.2, while another reported it did not help; treat that pin as a temporary, environment-specific mitigation.
What not to do: Do not assume every SDK or dependency combination is fixed by a blanket upgrade or pin.
Upstream status: HTTPX 0.28.0 released without the deprecated parameter; this evidence does not establish a particular fixed version for every third-party client.
Verification: Re-run the affected client construction and relevant application tests with the selected dependency set.
Remaining unknowns: The actual caller, installed SDK versions and whether the source-reported pin works in this environment.
Evidence classification: documented parameter removal; mixed source-reported workaround; no independent execution
UV package cache grows
Problem: The uv dependency cache is documented as disposable but useful, and uv cache clean or uv cache clean PACKAGE are documented native cleanup commands; deleting entries forces re-download or re-build when needed.
Affected environment: No measured size; excerpt selection only; uv cache prune scope and CI-specific options are not verified in the supplied excerpts and are not claimed here
What we know: The uv dependency cache is documented as disposable but useful, and uv cache clean or uv cache clean PACKAGE are documented native cleanup commands; deleting entries forces re-download or re-build when needed. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Identify uv cache location and compare size with disk budget.
Diagnostic procedure: Inspect the reported cache location and build/download activity; record size before cleanup.
How to interpret the result: A populated cache is expected; fast growth needs investigation.
Potential fixes and workarounds: uv documents cache clean and package-targeted cleaning; these discard reusable data and may require downloads. Use only under approved maintenance policy.
What not to do: Never delete arbitrary paths or clean without understanding scope.
Upstream status: Official documentation describes expected cache behavior, not a measured leak.
Verification: Confirm free space and later install behavior after separately approved maintenance.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
LiteLLM adds Gemini temperature when omitted
Problem: Returned optional params include temperature=1.0 although the caller did not set it; additional_drop_params=["temperature"] does not remove it because the default is added after the drop filter.
Affected environment: Vertex/Gemini config map_openai_params (SDK); Reporter reports reproduction on 1.82.0, 1.104.0, 1.104.2, 1.105.0rc3 and 1.106.0.dev2; get_optional_params / litellm.completion with Gemini 3 models (e.g. gemini/gemini-3.1-pro-preview) and no sampling params
What we know: Returned optional params include temperature=1.0 although the caller did not set it; additional_drop_params=["temperature"] does not remove it because the default is added after the drop filter. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check installed LiteLLM version and provider route.
Diagnostic procedure: Compare synthetic translated configuration with temperature omitted versus explicitly supplied; do not capture real prompts.
How to interpret the result: A default appearing only in the omitted case matches the report; provider rejection is not established.
Potential fixes and workarounds: Release notes list the change in 1.107.0rc1; evaluate this prerelease under compatibility policy. Explicit temperatures still pass through.
What not to do: Never expose credentials or prompts when inspecting payloads.
Upstream status: PR #45107 merged; 1.107.0rc1 is a prerelease, not proof of a stable fix.
Verification: Repeat synthetic translation checks on the candidate version and provider route.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
LiteLLM sync reasoning stream lacks closing events
Problem: The reasoning item gets output_item.added and deltas but no reasoning_summary_text.done, reasoning_summary_part.done or output_item.done, so it stays in_progress when the response completes. The async path closes it.
Affected environment: Responses API streaming iterator (litellm/responses/litellm_completion_transformation/streaming_iterator.py), sync __next__ path; v1.106.0 (as reported); litellm.responses(..., stream=True) consumed with a plain for loop, with reasoning effort high, on bridged models
What we know: The reasoning item gets output_item.added and deltas but no reasoning_summary_text.done, reasoning_summary_part.done or output_item.done, so it stays in_progress when the response completes. The async path closes it. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check LiteLLM version and streaming mode.
Diagnostic procedure: With a synthetic stream, capture event type names from sync and async iteration, without message text.
How to interpret the result: A difference isolated to sync resembles the report but does not prove internal cause.
Potential fixes and workarounds: The reporter describes an async comparison path; it is not a verified universal workaround.
What not to do: Do not log private prompts or apply an unreviewed patch.
Upstream status: Issue and PR #45582 were open at prior review; no released fix established.
Verification: Repeat the event-sequence comparison with exact dependencies.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
Databricks JSON request changes content shape
Problem: Reporter says a Databricks JSON-mode request returns HTTP 400 despite JSON appearing in the prompt, and attributes it to the bridge converting the string into text blocks.
Affected environment: chat to responses to chat bridge content transformation (Databricks provider); v1.100.0 (reporter-stated; production proxy and stock-pip repro)
What we know: The report attributes the 400 to transformed message content; the reproduction uses a mock endpoint and KFA did not independently execute it.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check the selected bridge and outgoing content shape.
Diagnostic procedure: Use a mock endpoint and synthetic JSON prompt to compare plain string and list content.
How to interpret the result: A 400 only for transformed shape is consistent with the report, not proof for every endpoint.
Potential fixes and workarounds: Merged PR #45686 targets single plain text blocks; release inclusion is unconfirmed.
What not to do: Do not remove validation or capture production prompts.
Upstream status: Change merged; deployed-release inclusion is not established.
Verification: Check installed version and test both text-only and multimodal cases.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
AutoGen positional-only FunctionTool arguments
Problem: The schema builds and arguments validate, but execution passes positional-only parameters as keyword arguments and fails.
Affected environment: autogen-core FunctionTool.run / run_json; autogen-core 0.7.5 at main commit 027ecf0a379bcc1d09956d46d12d44a3ad9cee14, Python 3.12.2, Windows (as reported); FunctionTool.run_json on a function with positional-only parameters
What we know: The schema builds and arguments validate, but execution passes positional-only parameters as keyword arguments and fails. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Inspect the function signature for positional-only arguments.
Diagnostic procedure: Use a disposable Python environment and minimal no-side-effect function through the same tool path.
How to interpret the result: A failure only with positional-only parameters matches the report; broader impact is unproven.
Potential fixes and workarounds: No released fix or tested wrapper is established.
What not to do: Do not silently alter production signatures or bypass validation.
Upstream status: Upstream issue open at screening; no linked released fix established.
Verification: Repeat with the exact installed package and Python versions.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
CrewAI cache-hit event reports a live call
Problem: On a cache hit, ToolUsageFinishedEvent.from_cache stays False although the executor's returned result says True, so traces cannot tell cached from live calls.
Affected environment: AgentExecutor native tool call events / telemetry; 1.15.22, repository main at commit 4ed2abc (per reporter); Native function-calling tool execution with a cache hit
What we know: On a cache hit, ToolUsageFinishedEvent.from_cache stays False although the executor's returned result says True, so traces cannot tell cached from live calls. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Identify executor path and compare returned cache state with event metadata.
Diagnostic procedure: Use a deterministic harmless synthetic tool, count actual invocations, and compare the second result and event.
How to interpret the result: A cache hit paired with a false event flag resembles the report; a trace alone does not prove a live call.
Potential fixes and workarounds: No verified upstream fix or supported wrapper is established.
What not to do: Do not use a sensitive live tool for the probe.
Upstream status: Issue open at prior review; no released fix established.
Verification: Compare actual invocation count and event fields with the deployed version.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
Async completion callback rejection escapes error path
Problem: An unhandled promise rejection is emitted; neither onError nor setError receives the failure, according to the reporter's mocked-fetch reproduction.
Affected environment: ui callCompletionApi (shared completion helper); ai@7.0.137 and upstream commit ba05943b69ad070558bb5bc912da99ec66d7d263 (reporter-tested); Node.js v26.7.0, macOS
What we know: An unhandled promise rejection is emitted; neither onError nor setError receives the failure, according to the reporter's mocked-fetch reproduction. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check callback return type and observed rejection path.
Diagnostic procedure: Use a synthetic completion and intentionally rejecting async callback in a disposable test; record error callback and process rejection.
How to interpret the result: A rejected promise without either error callback matches the report, not proof of provider failure.
Potential fixes and workarounds: No tested upstream fix is established; inspect application handling without claiming an unverified patch.
What not to do: Do not suppress global rejection reporting or capture real completions.
Upstream status: Issue closed without confirmed fix in prior review; reproduction PR #23279 closed unmerged.
Verification: Repeat the mock test on exact installed SDK version.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Kubernetes deleted ResourceClaim stays in mutation cache
Problem: After a generated claim is deleted and the informer observes the deletion, claimExists and findPodResourceClaim still return it from the mutation cache, so the controller does not recreate it until the entry expires (up to 1h TTL).
Affected environment: resourceclaim controller MutationCache; v1.37 (claimExists introduced by #140227); reproduced by reporter at commit 4dfdf5067a2
What we know: After a generated claim is deleted and the informer observes the deletion, claimExists and findPodResourceClaim still return it from the mutation cache, so the controller does not recreate it until the entry expires (up to 1h TTL). This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Confirm controller version and distinguish informer deletion from cache lookup.
Diagnostic procedure: Use an isolated unit test or disposable cluster with a synthetic claim and record deletion and reconciliation timing.
How to interpret the result: A persistent cache entry after observed deletion is consistent with the report; other stalls need separate diagnosis.
Potential fixes and workarounds: No merged fix or safe operational workaround is established.
What not to do: Do not delete production ResourceClaims for a diagnostic.
Upstream status: Issue closed by author; PR #142871 closed unmerged at source review.
Verification: Compare informer and cache behavior in the isolated test.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
LangChain file block missing in Responses conversion
Problem: The file block is removed from the Responses API request input, so only the text part is sent and the model replies as if no file was attached. No error is thrown.
Affected environment: converters/responses.ts convertMessagesToResponsesInput; @langchain/openai 1.6.2 with @langchain/core 1.2.14; reporter also reproduced on main at 62d6d6ba0
What we know: The file block is removed from the Responses API request input, so only the text part is sent and the model replies as if no file was attached. No error is thrown. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Confirm API mode and input block format.
Diagnostic procedure: Send a synthetic file block to mock fetch and compare input and outgoing request structure.
How to interpret the result: A missing block in the captured mock request matches the report.
Potential fixes and workarounds: No released fix is established; consult the supported input format for the installed version.
What not to do: Do not upload private files or assume a silent drop means a provider read them.
Upstream status: Issue remained open at screening; no released fix identified.
Verification: Retest the synthetic request after any version or format change.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
Gemini custom headers split at commas and colons
KFA Problem · Canonical KFA Solution
Problem: A header value containing a comma followed by text and a colon is split into extra entries; the real header loses part of its value and the extra names are invalid header names.
Affected environment: custom header parsing in core (packages/core/src/utils/customHeaderUtils.ts, parseCustomHeaders); main at commit c9096a847 (reporter-stated); released versions unknown
What we know: A header value containing a comma followed by text and a colon is split into extra entries; the real header loses part of its value and the extra names are invalid header names. This is reported in a public upstream source and was not independently reproduced by KFA. A current canonical KFA Solution documents a merged fix in a nightly prerelease.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check version and whether a synthetic value contains the delimiter pattern.
Diagnostic procedure: Use a fake header with commas and colons and inspect parsed names, never real credentials.
How to interpret the result: Unexpected extra header or invalid name matches the report; other parsing problems may differ.
Potential fixes and workarounds: Assess the cited 0.67.0 nightly under prerelease policy and verify with synthetic values; stable release inclusion unconfirmed.
What not to do: Never print actual authorization headers or secrets.
Upstream status: PR #29865 is merged and listed in the cited nightly; stable release inclusion unknown.
Verification: Compare synthetic parsing before and after any upgrade.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Gemini CLI search remains in Thinking state
Problem: The tool call stays pending for many minutes (31m+ in the original report; 42s to 853s per call in the ACP report) with the CLI in Thinking state. Esc aborts it.
Affected environment: built-in web search tool (GoogleSearch / google_web_search, WebSearchToolInvocation); Reported on CLI 0.61.0 (win32, no sandbox, Google sign-in); a commenter reports 0.60.0 on Linux in ACP mode. Other versions unknown
What we know: The tool call stays pending for many minutes (31m+ in the original report; 42s to 853s per call in the ACP report) with the CLI in Thinking state. Esc aborts it. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Identify CLI version, tool name and whether cancellation responds.
Diagnostic procedure: In a disposable session run a harmless query and record elapsed time and whether Escape cancels; do not retain query or account data.
How to interpret the result: A slow response differs from a persistent hang; cancellation is externally reported.
Potential fixes and workarounds: No released timeout fix established; reporter says Escape cancels.
What not to do: Do not kill unrelated processes or disclose private search text.
Upstream status: Issue closed; PR #29608 closed unmerged at source review.
Verification: Repeat within a bounded observation window and compare timing.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
Claude Code spins after config directory removal
Problem: After the config directory itself is removed, claude.exe CPU rises from near 0 to about 1.1 cores and stays there with no error, flat memory and no recovery. Separately, the process can reportedly outlive its closed console.
Affected environment: Windows config directory watcher and session shutdown; 2.1.292 (native claude.exe, Windows 11 Pro 10.0.26200 ARM64); Interactive session in a ConPTY with CLAUDE_CONFIG_DIR set to a temp dir that is then removed while the process runs
What we know: After the config directory itself is removed, claude.exe CPU rises from near 0 to about 1.1 cores and stays there with no error, flat memory and no recovery. Separately, the process can reportedly outlive its closed console. This is reported in a public upstream source and was not independently reproduced by KFA.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check whether directory removal coincides with CPU increase without reading contents.
Diagnostic procedure: Only in an isolated disposable session, observe before and after removal of a test directory and stop through normal controls.
How to interpret the result: Sustained increase after removal matches report; watcher cause remains unverified.
Potential fixes and workarounds: No released fix or independently verified workaround established.
What not to do: Never delete real configuration or terminate unrelated processes.
Upstream status: Issue open at screening; no released fix identified.
Verification: Compare a fresh test session retaining its test directory.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed
Primary sources: Source 1
ADK parallel agents share unexpected context
Problem: A reporter says one parallel single-turn sub-agent received its sibling’s output in shared-session context; an upstream collaborator disputes that interpretation.
Affected environment: context building / _get_current_turn_contents; 2.11.0 (reporter-stated; not independently verified)
What we know: The reporter attributes the observation to a reverse scan over shared session events. An upstream collaborator says the apparent block was parent content and the sibling event was dropped; KFA did not independently execute the report. ADK 2.13.0 release notes describe a related change.
Possible causes: The reported mechanism and applicability depend on the cited source; confirm the local environment before attributing the symptom.
Check this first: Check ADK version, parallel branches and shared session.
Diagnostic procedure: Use synthetic branch-specific markers without sensitive content and inspect each branch in a disposable test.
How to interpret the result: A crossing marker indicates unexpected context in that test, not a general security isolation guarantee.
Potential fixes and workarounds: ADK 2.13.0 release notes list branch and node-path isolation for parallel single-turn nodes; evaluate compatibility and retest.
What not to do: Never use secrets in test branches or rely on inferred isolation.
Upstream status: Issue closed and 2.13.0 release notes describe a related fix; exact application remains untested.
Verification: Repeat synthetic branch-marker test with the candidate release.
Remaining unknowns: The exact deployed environment, other versions and independent reproduction are not established by this research.
Evidence classification: source-reported; diagnostics are proposed checks, not independently executed