jenkinsci/jenkins · error · IllegalStateException

The class ${type.getName()} was not found, potentially not y

Error message

The class ${type.getName()} was not found, potentially not yet loaded

What it means

Thrown by ExtensionList.getInstance(Class) when iterating the loaded extension components finds none whose exact runtime class equals the requested type. Unlike lookup, this matches by getClass()==type (subclasses excluded), so a registered subclass or an interface type will not match. It is intended for an @Extension class to fetch its own singleton.

Source

Thrown at core/src/main/java/hudson/ExtensionList.java:154

    public @CheckForNull <U extends T> U get(@NonNull Class<U> type) {
        for (T ext : this)
            if (ext.getClass() == type)
                return type.cast(ext);
        return null;
    }

    /**
     * Looks for the extension instance of the given type (subclasses excluded),
     * or throws an IllegalStateException.
     *
     * Meant to simplify call inside @Extension annotated class to retrieve their own instance.
     */
    public @NonNull <U extends T> U getInstance(@NonNull Class<U> type) throws IllegalStateException {
        for (T ext : this)
            if (ext.getClass() == type)
                return type.cast(ext);

        throw new IllegalStateException("The class " + type.getName() + " was not found, potentially not yet loaded");
    }

    @Override
    public @NonNull Iterator<T> iterator() {
        // we need to intercept mutation, so for now don't allow Iterator.remove
        return new AdaptedIterator<>(Iterators.readOnly(ensureLoaded().iterator())) {
            @Override
            protected T adapt(ExtensionComponent<T> item) {
                return item.getInstance();
            }
        };
    }

    /**
     * Gets the same thing as the 'this' list represents, except as {@link ExtensionComponent}s.
     */
    public List<ExtensionComponent<T>> getComponents() {
        return Collections.unmodifiableList(ensureLoaded());

View on GitHub (pinned to 2e228ff40b)

Solutions

Use ExtensionList.lookup(Type.class).get(Type.class) for nullable lookup, or lookupFirst for highest-ordinal.
Ensure the extension is actually registered with @Extension and loaded (check Jenkins manage/extensions).
Pass the concrete @Extension class, not a superclass or interface.
If in a test, register the instance manually or use JenkinsRule before calling getInstance.

Example fix

// before
MyExt me = ExtensionList.lookup(ExtensionPoint.class).getInstance(MyExt.class);
// may throw if list is for the supertype; use the exact list
// after
MyExt me = ExtensionList.lookup(MyExt.class).getInstance(MyExt.class);

Defensive patterns

Strategy: type-guard

Validate before calling

ExtensionList<T> list = ExtensionList.lookup(MyExt.class);
if (!list.isEmpty() && list.stream().anyMatch(e -> e.getClass() == MyExt.class)) {
    MyExt me = list.getInstance(MyExt.class);
}

Type guard

static boolean hasExactInstance(Class<?> type) {
    return ExtensionList.lookup(type).stream().anyMatch(e -> e.getClass() == type);
}

Try / catch

try {
    MyExt me = ExtensionList.lookup(MyExt.class).getInstance(MyExt.class);
} catch (IllegalStateException e) {
    // 'was not found, potentially not yet loaded' — defer or fall back
}

Prevention

Call getInstance only for the concrete @Extension class, not an interface or superclass.
Prefer lookupFirst when you want graceful fallback to highest-ordinal.
Avoid calling during early bootstrap; wait for Jenkins to be fully loaded.

When it happens

Trigger: Calling getInstance on a type with no exact-class instance; calling it before the extension list has been loaded; passing an interface or superclass instead of the concrete @Extension class; the instance is registered under a different ExtensionList (wrong Jenkins).

Common situations: Calling getInstance too early during startup; the extension failed to load (check logs); refactor renamed/moved the class so the registered class differs; multiple Jenkins instances in tests.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/0897c29b9fd6d51e. Report an issue: GitHub.