{"record":{"id":"44a62ab784f84475","repo":"langgenius/dify","slug":"usage-missing-arg","errorCode":"usage_missing_arg","errorMessage":"device_label is required","messagePattern":"device_label is required","errorType":"error_code","errorClass":"BaseError","httpStatus":null,"severity":"error","filePath":"cli/src/api/oauth-device.ts","lineNumber":73,"sourceCode":"  | { status: 'approved'; success: PollSuccess }\n\nconst POLL_ERROR_TO_STATUS: Record<string, PollResult['status']> = {\n  authorization_pending: 'pending',\n  slow_down: 'slow_down',\n  expired_token: 'expired',\n  access_denied: 'denied',\n}\n\nexport class DeviceFlowApi {\n  private readonly http: HttpClient\n\n  constructor(http: HttpClient) {\n    this.http = http\n  }\n\n  async requestCode(req: CodeRequest): Promise<CodeResponse> {\n    if (req.device_label === '') {\n      throw new BaseError({\n        code: ErrorCode.UsageMissingArg,\n        message: 'device_label is required',\n      })\n    }\n    const body = { client_id: req.client_id ?? DEFAULT_CLIENT_ID, device_label: req.device_label }\n    const res = await this.http.fetch('oauth/device/code', { method: 'POST', json: body })\n    if (res.status === 404) throw versionSkew()\n    if (!res.ok) {\n      throw new HttpClientError({\n        code: ErrorCode.Server4xxOther,\n        message: `device/code: HTTP ${res.status}`,\n        httpStatus: res.status,\n      })\n    }\n    return (await res.json()) as CodeResponse\n  }\n\n  async pollOnce(req: PollRequest): Promise<PollResult> {","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/langgenius/dify/blob/ef8544b173fd6cd7a8e71df2cab576e52bebbfbc/cli/src/api/oauth-device.ts#L55-L91","documentation":"Raised by DatasetsHitTestingBase.perform_hit_testing when the response dict from HitTestingService.retrieve has a 'query' field that is not a dict, or whose 'content' entry is not a string. This guards the retrieval-service contract before the controller reshapes the response. It is an internal server error surfaced as ValueError and ultimately HTTP 500 via the catch-all except clause.","triggerScenarios":"HitTestingService.retrieve returns a dict missing the 'query' key, returns query as None or a string, or returns query.content as a non-string (e.g. a dict). Happens after a retrieval-backend regression or a partial failure that returned an empty/malformed response.","commonSituations":"A new retrieval mode forgot to populate the query echo; an external knowledge adapter returned only records without echoing the query; a refactor changed the retrieve return type without updating this contract check.","solutions":["Check server logs (logger.exception logs the full traceback) to see the actual shape returned by HitTestingService.retrieve.","Fix the retrieval implementation to always return {'query': {'content': <str>}, 'records': [...]} .","Add an integration test asserting retrieve returns the documented contract."],"exampleFix":"# before\nreturn {\"records\": retrieved_records}\n# after\nreturn {\"query\": {\"content\": query_text}, \"records\": retrieved_records}","handlingStrategy":"type-guard","validationCode":"from typing import Any, cast\n\ndef validate_retrieve_response(response: Any) -> dict:\n    if not isinstance(response, dict):\n        raise TypeError('retrieve must return a dict')\n    q = response.get('query')\n    if not isinstance(q, dict) or not isinstance(q.get('content'), str):\n        raise TypeError('retrieve response.query must be {content: str}')\n    return response\n# call in HitTestingService.retrieve before returning","typeGuard":"from typing import Any\n\ndef is_query_echo(value: Any) -> bool:\n    return isinstance(value, dict) and isinstance(value.get('content'), str)","tryCatchPattern":"try:\n    response = HitTestingService.retrieve(...)\nexcept Exception:\n    logger.exception('retrieve failed')\n    raise InternalServerError('hit testing failed')\n# Note: the malformed-shape ValueError is a server bug; not retryable.","preventionTips":["Pin the retrieve return type with a typed dataclass/pydantic model and validate it in the service.","Add integration tests that assert the {query:{content:str}, records:[...]} contract.","Review any retrieval-adapter change for the echoed-query field."],"tags":["hit-testing","internal","validation","response-shape","retrieval","server-error"],"backgroundTag":null,"analyzedSha":"ef8544b173fd6cd7a8e71df2cab576e52bebbfbc","analyzedAt":"2026-08-12T05:15:17.394Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}