{"record":{"id":"494cd184f008194c","repo":"apache/shenyu","slug":"import-failed","errorCode":null,"errorMessage":"Import failed: ","messagePattern":"Import failed: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java","lineNumber":119,"sourceCode":"            \n            // 4. Create virtual instance\n            UpstreamInstance instance = createVirtualInstance(request);\n            \n            // 5. Parse and save document\n            docManager.addDocInfo(instance, swaggerJson, null, docInfo -> {\n                LOG.info(\"Successfully imported swagger document: {} with MD5: {}\", \n                    request.getProjectName(), docInfo.getDocMd5());\n            });\n            \n            return \"Import successful, supports Swagger 2.0 and OpenAPI 3.0 formats\";\n            \n        } catch (IllegalArgumentException e) {\n            // Keep bad user input unwrapped so the controller can return HTTP 400.\n            LOG.error(\"Failed to import swagger document: {}\", request.getProjectName(), e);\n            throw e;\n        } catch (Exception e) {\n            LOG.error(\"Failed to import swagger document: {}\", request.getProjectName(), e);\n            throw new RuntimeException(\"Import failed: \" + e.getMessage(), e);\n        }\n    }\n\n    @Override\n    public String importMcpConfig(final SwaggerImportRequest request) {\n        LOG.info(\"Start importing Mcp config: {}\", request);\n\n        try {\n            validateSwaggerUrl(request.getSwaggerUrl());\n\n            String swaggerJson = fetchSwaggerDoc(request.getSwaggerUrl());\n\n            String namespaceId = StringUtils.defaultIfEmpty(request.getNamespaceId(), SYS_DEFAULT_NAMESPACE_ID);\n            List<McpToolsRegisterDTO> mcpToolsRegisterDTOList = buildMcpToolRegisterDTO(swaggerJson, namespaceId);\n\n            mcpToolsRegisterDTOList.forEach(mcpToolsRegisterDTO -> {\n                shenyuClientRegisterMcpService.registerMcpTools(mcpToolsRegisterDTO);\n            });","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/apache/shenyu/blob/567142e07261b3e615ae8850b30f4421f455cc5d/shenyu-admin/src/main/java/org/apache/shenyu/admin/service/impl/SwaggerImportServiceImpl.java#L101-L137","documentation":"importSwagger() wraps any unexpected exception from the swagger import pipeline into a RuntimeException with the prefix 'Import failed: ' plus the underlying message. It is a catch-all so the controller gets a single failure path, while IllegalArgumentException (bad user input) is deliberately re-thrown unwrapped so the controller can map it to HTTP 400. Seeing this message means the import failed for a non-validation reason (IO, parsing, downstream service errors).","triggerScenarios":"Calling the swagger import API (SwaggerImportServiceImpl.importSwagger) when any step throws a non-IllegalArgumentException Exception: reading/fetching the swagger document fails, JSON parsing blows up unexpectedly, or downstream registration code throws. The original cause is attached as the cause of the RuntimeException.","commonSituations":"The swagger URL points to a service that is down or returns garbage; the admin server cannot reach the target host; the document passes basic validation but fails later parsing/mapping; database or namespace registration steps fail mid-import.","solutions":["Read the 'cause' stack trace of this RuntimeException to find the real failure (IO error, parse error, etc.) — the wrapper message alone is not diagnostic.","Verify the swaggerUrl is reachable from the admin server (curl it from the same host/network).","Confirm the document is valid Swagger 2.0/OpenAPI 3.0 JSON so it passes validateSwaggerContent before deeper processing.","If it should be a 400-style validation problem, throw IllegalArgumentException in the underlying code instead of a generic Exception so it is not wrapped."],"exampleFix":"// before: service throws generic exception which gets wrapped\nthrow new Exception(\"something broke\");\n// after: use IllegalArgumentException for user-input problems so controller returns 400\nthrow new IllegalArgumentException(\"projectName must not be blank\");","handlingStrategy":"try-catch","validationCode":"try (Response r = new OkHttpClient().newCall(new Request.Builder().url(swaggerUrl).build()).execute()) {\n    if (r.code() != 200 || r.body() == null) throw new IllegalStateException(\"swagger URL not fetchable: \" + r.code());\n    JsonParser.parseString(r.body().string()); // must be parseable JSON\n}","typeGuard":null,"tryCatchPattern":"try {\n    swaggerImportService.importSwagger(request);\n} catch (IllegalArgumentException e) {\n    return ResponseEntity.badRequest().body(e.getMessage()); // validation problem\n} catch (RuntimeException e) {\n    log.error(\"import failed\", e.getCause()); // inspect cause for the real error\n    return ResponseEntity.status(502).body(\"import failed: \" + e.getCause().getMessage());\n}","preventionTips":["Always log/read e.getCause() — the wrapper message is never the root cause.","Pre-validate the swagger URL with a curl/HEAD request before importing.","Validate swagger content client-side before calling the import API.","Distinguish validation failures (400) from infrastructure failures (5xx) in your caller code."],"tags":["swagger","import","runtime-exception","error-wrapping"],"backgroundTag":"api-request-failed","analyzedSha":"567142e07261b3e615ae8850b30f4421f455cc5d","analyzedAt":"2026-09-12T10:08:21.293Z","contentChangedAt":"2026-09-12T10:08:21.293Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}