{"record":{"id":"af0e0b688cbbb261","repo":"iflytek/astron-agent","slug":"internal-server-error-operation-callable-name-err-unexpected","errorCode":null,"errorMessage":"Internal server error:${operation_callable.__name__} err (Unexpected), reason {e}","messagePattern":"Internal server error:(.+?) err \\(Unexpected\\), reason (.+?)","errorType":"http","errorClass":"ServiceException","httpStatus":null,"severity":"critical","filePath":"core/knowledge/api/v1/api.py","lineNumber":160,"sourceCode":"        logger.error(error_msg)\n        span_context.record_exception(e)\n        metric.in_error_count(code=e.code)\n        # Create a CodeEnum-like object for the response\n        error_code = type(\"ErrorCode\", (), {\"code\": e.code, \"msg\": e.message})()\n        return ErrorResponse(code_enum=error_code, message=e.message)\n\n    except CustomException as e:\n        error_msg = f\"{operation_callable.__name__} err (Custom), reason {e}\"\n        logger.error(error_msg)\n        span_context.record_exception(e)\n        metric.in_error_count(code=e.code)\n        # Create a CodeEnum-like object for the response\n        error_code = type(\"ErrorCode\", (), {\"code\": e.code, \"msg\": e.message})()\n        return ErrorResponse(code_enum=error_code, message=e.message)\n\n    except Exception as e:  # pylint: disable=W0718\n        # Intentionally catch all exceptions here as part of global exception handling\n        error_msg = f\"{operation_callable.__name__} err (Unexpected), reason {e}\"\n        logger.error(error_msg)\n        span_context.record_exception(e)\n        metric.in_error_count(code=CodeEnum.ServiceException.code)\n        return ErrorResponse(\n            code_enum=CodeEnum.ServiceException,\n            message=f\"Internal server error:{error_msg}\",\n        )\n\n\n# --- Route Handler Functions ---\n\n\nclass DatasetCreateRequest(BaseModel):\n    \"\"\"Request body for POST /v1/dataset/create.\"\"\"\n\n    name: str = Field(\n        ...,\n        min_length=1,","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/api/v1/api.py#L142-L178","documentation":"The final except Exception branch in handle_rag_operation is the catch-all for unexpected errors. It logs 'err (Unexpected)', records the span, increments the ServiceException metric, and returns an ErrorResponse with CodeEnum.ServiceException and message 'Internal server error:<op> err (Unexpected), reason <e>'. This is the generic 500-style response for the RAG endpoints.","triggerScenarios":"Any uncaught exception during file_split, file_upload, chunk_save/update/delete/query: programming bugs (TypeError, AttributeError, KeyError), infrastructure failures (DB, Redis, MinIO) not wrapped as Custom/ThirdPartyException, unpicklable payloads, timeouts from untyped clients.","commonSituations":"Schema drift between request model and service code; missing dependency at runtime; database connection pool exhausted; refactoring left a stale attribute access.","solutions":["Read 'reason <e>' in the response/log to identify the actual exception type and stack trace from the logger output","Fix the underlying bug or infrastructure failure identified in the traceback","Wrap expected infrastructure failures as CustomException/ThirdPartyException so they map to proper codes","Add specific exception handling for recurring failure modes instead of relying on the catch-all"],"exampleFix":"// before\nchunk.save()  # AttributeError if collection missing -> Internal server error\n// after\nif collection is None:\n    raise CustomException(code=CodeEnum.ServiceException.code, message=\"collection not initialized\")\ncollection.save(chunk)","handlingStrategy":"try-catch","validationCode":"# client-side: fail fast on obviously bad payloads before the call\nassert payload and isinstance(payload, dict), \"empty/invalid payload for RAG operation\"","typeGuard":"def is_internal_error(resp: dict) -> bool:\n    return isinstance(resp, dict) and str(resp.get(\"message\", \"\")).startswith(\"Internal server error:\")","tryCatchPattern":"try:\n    resp = rag_api.file_split(payload)\nexcept Exception:\n    log.exception(\"RAG call failed unexpectedly\")\n    resp = retry_once(payload) or degraded_response()","preventionTips":["Never rely on the catch-all for known failure modes — wrap them as Custom/ThirdPartyException","Run service tests covering all six wrapped operations to surface Type/Attribute errors early","Monitor the ServiceException metric for spikes after deployments","Pin and verify runtime dependencies to avoid missing-module failures"],"tags":["python","fastapi","unhandled-exception","internal-server-error","rag"],"backgroundTag":"internal-invariant-violation","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}