apache/skywalking · critical · IllegalArgumentException

OpenAPI definition file: {file.getAbsolutePath()} found in r

Error message

OpenAPI definition file: {file.getAbsolutePath()} found in root directory, but doesn't include x-sw-service-name extensive definition in the file.

What it means

When loading OpenAPI definitions for endpoint grouping, EndpointGroupingRuleReader4Openapi derives the service name either from the 'x-sw-service-name' extension field in the file or, failing that, from the name of the directory containing the file. If neither exists — the file sits directly in the configured root directory AND lacks x-sw-service-name — the service name is ambiguous, so the reader throws IllegalArgumentException.

Source

Thrown at oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/config/group/openapi/EndpointGroupingRuleReader4Openapi.java:139

            }
            Reader reader = new StringReader(openapiDefs);
            Yaml yaml = new Yaml(new SafeConstructor(new LoaderOptions()));
            Map openapiData = yaml.load(reader);
            if (openapiData != null) {
                serviceOpenapiDefMap.computeIfAbsent(getServiceName(serviceName, openapiData), k -> new ArrayList<>())
                                    .add(openapiData);
            }
        });

        return serviceOpenapiDefMap;
    }

    private String getServiceName(String openapiDefPath, File file, Map openapiData) {
        String serviceName = (String) openapiData.get("x-sw-service-name");
        if (StringUtil.isEmpty(serviceName)) {
            File directory = new File(file.getParent());
            if (openapiDefPath.equals(directory.getName())) {
                throw new IllegalArgumentException(
                    "OpenAPI definition file: " + file.getAbsolutePath() + " found in root directory, but doesn't include x-sw-service-name extensive definition in the file.");
            }
            serviceName = directory.getName();
        }

        return serviceName;
    }

    private String getServiceName(String defaultServiceName, Map openapiData) {
        String serviceName = (String) openapiData.get("x-sw-service-name");
        if (StringUtil.isEmpty(serviceName)) {
            serviceName = defaultServiceName;
        }

        return serviceName;
    }

    private boolean isTemplatePath(String pathString) {

View on GitHub (pinned to 102af09b4a)

Solutions

1. Move the file into a subdirectory named after its service (e.g. open-apis/my-service/service.yaml); the directory name becomes the service name.
2. Or add the extension field to the spec: 'x-sw-service-name: my-service' at the document root.
3. If multiple specs belong to one service, keep them in that service's subdirectory or give each the same x-sw-service-name.
4. Restart OAP after fixing.

Example fix

# open-apis/root-level-spec.yaml — before (in root dir, no extension)
openapi: 3.0.0
info:
  title: demo

# after (option A: keep in root, add extension)
openapi: 3.0.0
info:
  title: demo
x-sw-service-name: demo-service

# after (option B: move file to open-apis/demo-service/demo.yaml)

// Pre-check openapi dir layout before boot
Path root = Path.of(openapiDir);
try (Stream<Path> files = Files.list(root)) {
    for (Path p : files.filter(Files::isRegularFile).collect(Collectors.toList())) {
        Map spec = yaml.load(Files.readString(p));
        boolean hasName = spec != null && spec.containsKey("x-sw-service-name");
        if (!hasName) throw new ConfigException("root-level spec lacks x-sw-service-name: " + p);
    }
}

Not applicable — startup config error; fix file placement or spec.

When it happens

Trigger: An OpenAPI definition file placed in the root of the openapi definitions directory (its parent directory equals the configured root path, checked via openapiDefPath.equals(directory.getName())) without an 'x-sw-service-name' field in its top-level map.

Common situations: Dropping petstore.yaml straight into the open-apis folder instead of a per-service subfolder; enabling openapi grouping (core.openapi-endpoint-grouping) on an existing folder of flat YAML files; removing the extension field during spec cleanup or regeneration from an upstream spec that never had it.

Related errors

• service-name can't be empty
• Component name [{name}] in Component-Server-Mappings doesn't
• Server componentId name [{serverName}] in Component-Server-M
• HierarchyRuleProvider did not produce a matcher for rule: {e
• hierarchy-definition.yml {layer} is not a valid layer name.

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/f0757850ee03e534. Report an issue: GitHub.