quarkusio/quarkus · error · IllegalStateException

Failed to deserialize registries descriptor ${file}

Error message

Failed to deserialize registries descriptor ${file}

What it means

After the registry descriptor artifact is resolved, buildRegistryClient() parses it with RegistryConfig.mutableFromFile(). If reading/deserializing the descriptor JSON file throws IOException, an IllegalStateException wrapping the IOException is thrown, reporting the artifact file path. This means the downloaded (or cached) registry descriptor file exists but could not be read or parsed.

Source

Thrown at independent-projects/tools/registry-client/src/main/java/io/quarkus/registry/client/maven/MavenRegistryClientFactory.java:129

                        break;
                    }
                }
                if (srcRepoUrl == null) {
                    throw new IllegalStateException(
                            "Failed to locate the repository URL corresponding to repository " + srcRepoId);
                }
            } else {
                log.debug("Failed to determine the remote repository for %s registry descriptor %s", config.getId(),
                        registryDescriptorCoords);
            }
        }

        final RegistryConfig.Mutable descriptor;
        try {
            // Do not fix or add any missing bits.
            descriptor = RegistryConfig.mutableFromFile(result.getArtifact().getFile().toPath());
        } catch (IOException e) {
            throw new IllegalStateException("Failed to deserialize registries descriptor " + result.getArtifact().getFile(), e);
        }

        if (!isComplete(config, descriptor)) {
            config = completeRegistryConfig(config, descriptor);
        }

        final MavenRegistryArtifactResolver registryArtifactResolver = newRegistryArtifactResolver(resolver,
                cleanupTimestampedArtifacts);

        return new RegistryClientDispatcher(config,
                getPlatformsResolver(config, registryArtifactResolver),
                getPlatformExtensionsResolver(config, registryArtifactResolver, cleanupTimestampedArtifacts),
                getNonPlatformExtensionsResolver(config, registryArtifactResolver),
                new MavenRegistryCache(config, registryArtifactResolver, log));
    }

    private List<RemoteRepository> applyMirrorsAndProxies(List<RemoteRepository> registryRepos) {
        return originalResolver.getRemoteRepositoryManager().aggregateRepositories(

View on GitHub (pinned to e1c734241f)

Solutions

1. Delete the descriptor artifact directory under ~/.m2/repository (e.g. io/quarkus/registry/...) to purge the corrupt cached file and re-resolve
2. Check the artifact file content — if it contains HTML/errors, a proxy or mirror is intercepting; fix or bypass the proxy/mirror
3. Verify file permissions/locks on the artifact path and available disk space (CI shared caches, Windows AV)
4. Re-run the build after fixing; if persistent, upgrade the registry client/Quarkus version and re-download

Example fix

// before: corrupt cached descriptor
rm -rf ~/.m2/repository/io/quarkus/registry/
// after: clean re-resolution succeeds
./mvnw -U quarkus:add-extension -Dextensions="io.quarkus:quarkus-rest"

// validate the descriptor file before handing it to the client
Path p = Paths.get(artifactFile);
if (!Files.isReadable(p)) throw new IllegalStateException("Descriptor not readable: " + p);
try (var in = Files.newInputStream(p)) {
    byte[] head = in.readNBytes(1);
    if (head.length == 0 || head[0] == '<') throw new IllegalStateException("Descriptor looks like HTML/proxy error page: " + p);
}

try {
    client = factory.buildRegistryClient(config);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to deserialize registries descriptor")) {
        // purge the corrupt artifact and retry once
        deleteArtifactDir(artifactFile);
        client = factory.buildRegistryClient(config);
    } else throw e;
}

When it happens

Trigger: Calling buildRegistryClient(config) where the resolved descriptor artifact file on disk is unreadable (permissions), truncated/corrupt (interrupted download), or otherwise fails I/O during RegistryConfig.mutableFromFile().

Common situations: Corrupted local Maven cache entry (~/.m2/repository partial download); a mirror/proxy returning an HTML error page saved as the artifact; file permission issues on shared CI caches; disk full; antivirus locking the file on Windows.

Related errors

• Unexpected end of stream while reading application config fi
• Failed to deserialize extension metadata from ${url}
• Failed to open path tree with root %s
• Failed to read %s
• Failed to read resources from classpath

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