What causes "Failed to load codestart spec: + resourceName" in quarkusio/quarkus?

Validate the codestart.yml syntax (run it through a YAML parser) and fix parse errors.

quarkusio/quarkus · error · CodestartStructureException

Failed to load codestart spec: + resourceName

Error message

Failed to load codestart spec: + resourceName

What it means

CodestartCatalogLoader.loadCodestarts() wraps IOException and JacksonException when parsing a codestart spec file (codestart.yml) into a CodestartStructureException('Failed to load codestart spec: <resourceName>'). It signals a malformed or unreadable codestart definition in a codestarts directory or jar resource.

Source

Thrown at independent-projects/tools/codestarts/src/main/java/io/quarkus/devtools/codestarts/CodestartCatalogLoader.java:95

        try {
            return pathLoader.loadResourceAsPath(directoryName,
                    path -> {
                        try (final Stream<Path> pathStream = Files.walk(path)) {
                            return pathStream
                                    .filter(p -> p.getFileName().toString().matches("codestart\\.yml$"))
                                    .map(p -> {
                                        final String resourceName = resolveResourceName(directoryName, path, p);
                                        try {
                                            final CodestartSpec spec = readCodestartSpec(new String(Files.readAllBytes(p)));
                                            final String resourceCodestartDirectory = resourceName.replaceAll(
                                                    "/?codestart\\.yml",
                                                    "");
                                            return new Codestart(
                                                    new PathCodestartResourceAllocator(pathLoader, resourceCodestartDirectory),
                                                    spec,
                                                    resolveImplementedLanguages(p.getParent()));
                                        } catch (IOException | tools.jackson.core.JacksonException e) {
                                            throw new CodestartStructureException(
                                                    "Failed to load codestart spec: " + resourceName,
                                                    e);
                                        }
                                    }).collect(Collectors.toList());
                        }
                    });
        } catch (IOException e) {
            return Collections.emptyList();
        }
    }

    private static Set<String> resolveImplementedLanguages(Path p) throws IOException {
        // empty means all
        try (final Stream<Path> files = Files.list(p)) {
            return files
                    .filter(Files::isDirectory)
                    .map(CodestartCatalogLoader::getDirName)
                    .filter(l -> !Objects.equals(l, BASE_LANGUAGE))

View on GitHub (pinned to e1c734241f)

Solutions

Validate the codestart.yml syntax (run it through a YAML parser) and fix parse errors.
Check the spec against the expected Codestart schema (name, type, language, required fields).
Verify the resource is correctly packaged and its path/name matches what the catalog loader expects.

Example fix

# before (codestart.yml)
name: my-codstart
type: project  # unknown enum/typo breaks Jackson
# after
name: my-codestart
type: project

Defensive patterns

Strategy: validation

Validate before calling

// validate codestart.yml before packaging
try (var in = Files.newInputStream(specPath)) {
    new org.yaml.snakeyaml.Yaml().load(in); // syntax check
} catch (IOException | org.yaml.snakeyaml.error.YAMLException e) {
    throw new IllegalStateException("Invalid codestart spec: " + specPath, e);
}

Try / catch

try {
    catalog = CodestartCatalogLoader.loadCodestarts(dir, ...);
} catch (CodestartStructureException e) {
    if (e.getMessage().startsWith("Failed to load codestart spec")) {
        logger.error("Fix codestart.yml: " + e.getCause());
    }
    throw e;
}

Prevention

Lint custom codestart.yml files in CI (YAML parse + schema check).
Keep codestart specs matching the Quarkus version's expected schema.
Verify resources are packaged in the jar (check built artifact contents).

When it happens

Trigger: A codestart spec YAML under a loaded codestarts directory cannot be read (IOException) or fails Jackson deserialization (JacksonException) — e.g. invalid YAML syntax, wrong schema fields, or a missing/corrupt resource on the classpath.

Common situations: Custom codestarts added to a project with YAML typos; wrong spec structure after a Quarkus version change; corrupted jar packaging of custom codestart resources.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/d2672343853b2858. Report an issue: GitHub.