quarkusio/quarkus · error · IllegalStateException

Unable load class '''

Error message

Unable load class '''

What it means

At request time, RestLinksHandler.entityTypeClass loads the stored entity type name via the thread context class loader to serve link lookups. If the class cannot be loaded (ClassNotFoundException), it throws IllegalStateException 'Unable load class <name>'.

Source

Thrown at extensions/resteasy-reactive/rest-links/runtime/src/main/java/io/quarkus/resteasy/reactive/links/RestLinksHandler.java:48

            response.getHeaders().add("Link", link);
        }
    }

    private Collection<Link> getLinks(Response response) {
        RestLinksProvider provider = getRestLinksProvider();

        if ((restLinkData.getRestLinkType() == RestLinkType.INSTANCE) && response.hasEntity()) {
            return provider.getInstanceLinks(response.getEntity());
        }
        return provider.getTypeLinks(
                restLinkData.getEntityType() != null ? entityTypeClass() : response.getEntity().getClass());
    }

    private Class<?> entityTypeClass() {
        try {
            return Thread.currentThread().getContextClassLoader().loadClass(restLinkData.getEntityType());
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("Unable load class '" + restLinkData.getEntityType() + "'", e);
        }
    }

    private RestLinksProvider getRestLinksProvider() {
        return Arc.container().instance(RestLinksProvider.class).get();
    }

    public static class RestLinkData {

        public RestLinkData(RestLinkType restLinkType, String entityType) {
            this.restLinkType = restLinkType;
            this.entityType = entityType;
        }

        public RestLinkData() {
        }

        private RestLinkType restLinkType;

View on GitHub (pinned to e1c734241f)

Solutions

1. Do a clean rebuild (./mvnw clean install) so recorded metadata matches current classes.
2. Verify the entity class name in the rest-links config/code still exists and is spelled correctly.
3. Ensure the call happens on a Quarkus-managed thread where the TCCL is the application classloader.

Example fix

// before
class Order { ... } // renamed from Orders, old recorded data
// after: clean rebuild and update references from Orders -> Order

try { Thread.currentThread().contextClassLoader.loadClass(entityTypeName) } catch (e: ClassNotFoundException) { /* stale build or renamed entity */ }

try {
  linksProvider.getLinks(entity)
} catch (e: IllegalStateException) {
  logger.error("rest-links entity class not loadable: ${e.message}")
  throw e
}

When it happens

Trigger: Calling RestLinksProvider/RestLinks.getLinks where the recorded entity type name is not loadable at runtime — e.g. the class was in an unindexed jar at build (so no handler) or was removed/renamed between builds; stale build artifacts; TCCL not set to the app classloader in a custom threading context.

Common situations: Hot-reload/quirks after refactoring entity names; running serialized data referencing old class names; calling the links API from a thread with a wrong context classloader.

Related errors

• Can not load class []
• Failed to load steps from %s
• The class (${name}) cannot be created during deployment.
• Cannot find ClassLoadingRecorder.class on classpath
• Failed to load the condition class ${testClassName} for capa

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