iflytek/astron-agent · critical · ServiceException

Internal server error

Error message

Internal server error:${operation_callable.__name__} err (Unexpected), reason {e}

What it means

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.

Solutions

1. Read 'reason <e>' in the response/log to identify the actual exception type and stack trace from the logger output
2. Fix the underlying bug or infrastructure failure identified in the traceback
3. Wrap expected infrastructure failures as CustomException/ThirdPartyException so they map to proper codes
4. Add specific exception handling for recurring failure modes instead of relying on the catch-all

Example fix

// before
chunk.save()  # AttributeError if collection missing -> Internal server error
// after
if collection is None:
    raise CustomException(code=CodeEnum.ServiceException.code, message="collection not initialized")
collection.save(chunk)

# client-side: fail fast on obviously bad payloads before the call
assert payload and isinstance(payload, dict), "empty/invalid payload for RAG operation"

def is_internal_error(resp: dict) -> bool:
    return isinstance(resp, dict) and str(resp.get("message", "")).startswith("Internal server error:")

try:
    resp = rag_api.file_split(payload)
except Exception:
    log.exception("RAG call failed unexpectedly")
    resp = retry_once(payload) or degraded_response()

When it happens

Trigger: 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.

Common situations: Schema drift between request model and service code; missing dependency at runtime; database connection pool exhausted; refactoring left a stale attribute access.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.

Related errors

• (ThirdPartyException ErrorResponse)
• (CustomException ErrorResponse)
• SparkDesk-RAG does not support split operation.
• SparkDesk-RAG does not support chunks_save operation.
• SparkDesk-RAG does not support chunks_update operation.

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/af0e0b688cbbb261. Report an issue: GitHub.

Appendix: source

Thrown at core/knowledge/api/v1/api.py:160

        logger.error(error_msg)
        span_context.record_exception(e)
        metric.in_error_count(code=e.code)
        # Create a CodeEnum-like object for the response
        error_code = type("ErrorCode", (), {"code": e.code, "msg": e.message})()
        return ErrorResponse(code_enum=error_code, message=e.message)

    except CustomException as e:
        error_msg = f"{operation_callable.__name__} err (Custom), reason {e}"
        logger.error(error_msg)
        span_context.record_exception(e)
        metric.in_error_count(code=e.code)
        # Create a CodeEnum-like object for the response
        error_code = type("ErrorCode", (), {"code": e.code, "msg": e.message})()
        return ErrorResponse(code_enum=error_code, message=e.message)

    except Exception as e:  # pylint: disable=W0718
        # Intentionally catch all exceptions here as part of global exception handling
        error_msg = f"{operation_callable.__name__} err (Unexpected), reason {e}"
        logger.error(error_msg)
        span_context.record_exception(e)
        metric.in_error_count(code=CodeEnum.ServiceException.code)
        return ErrorResponse(
            code_enum=CodeEnum.ServiceException,
            message=f"Internal server error:{error_msg}",
        )


# --- Route Handler Functions ---


class DatasetCreateRequest(BaseModel):
    """Request body for POST /v1/dataset/create."""

    name: str = Field(
        ...,
        min_length=1,

View on GitHub (pinned to 5e758547a8)