quarkusio/quarkus · error · RuntimeException

Could not find component reference

Error message

Could not find component reference

What it means

Page.getComponentRef() computes the web-component path for the page: an internal page resolves to ./../qwc/<componentLink>, a namespaced page to ./../<namespace>/<componentLink>. If internalComponent is false and namespace is null, no reference can be built and the library throws (the planned not-found component does not exist yet).

Source

Thrown at extensions/devui/deployment-spi/src/main/java/io/quarkus/devui/spi/page/Page.java:119

            if (d.equals(this.namespace)) {
                return id;
            } else {
                int i = this.namespace.indexOf(DASH) + 1;
                String stripDevui = this.namespace.substring(i);
                return stripDevui + DASH + id;
            }
        }
        return id;
    }

    public String getComponentRef() {
        if (internalComponent) {
            return DOT + SLASH + DOT + DOT + SLASH + "qwc" + SLASH + this.componentLink;
        } else if (this.namespace != null) {
            return DOT + SLASH + DOT + DOT + SLASH + this.namespace + SLASH + this.componentLink;
        }
        // TODO: Create a not found component to display here ?
        throw new RuntimeException("Could not find component reference");
    }

    public String getNamespace() {
        return this.namespace;
    }

    public String getNamespaceLabel() {
        return this.namespaceLabel;
    }

    public String getIcon() {
        return icon;
    }

    public String getColor() {
        return color;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the namespace: pageBuilder.namespace("org.acme") so the ref resolves to ./../org.acme/<componentLink>
2. For Dev-UI-internal components use the internal component builders (WebComponentPageBuilder/QuteDataPageBuilder) which set internalComponent=true and the qwc namespace
3. Build pages via PageBuilder.build() rather than constructing Page manually — build() guesses component links and namespaces
4. Verify any custom code copying pages preserves the namespace field

Example fix

// before
PageBuilder pb = new WebComponentPageBuilder()
        .componentLink("qwc-foo.js");
// getComponentRef() later throws (no namespace)
// after
PageBuilder pb = new WebComponentPageBuilder()
        .namespace("org.acme")
        .componentLink("qwc-foo.js");

if (!page.isInternalComponent() && page.getNamespace() == null) {
    throw new IllegalStateException("Page needs a namespace (or internal component) before computing component ref");
}

boolean hasComponentRef(Page p) {
    return p != null && (p.isInternalComponent() || (p.getNamespace() != null && !p.getNamespace().isBlank()));
}

try {
    String ref = page.getComponentRef();
} catch (RuntimeException e) {
    if (e.getMessage().contains("Could not find component reference")) {
        log.warnf("Page without namespace skipped: %s", page);
    } else throw e;
}

When it happens

Trigger: Calling getComponentRef() on a Page built without namespace(...) and with internalComponent=false — e.g. a page created with only a componentLink but never marked internal nor given a namespace.

Common situations: Custom builders or extension code constructing Page objects directly instead of via PageBuilder; external pages whose namespace assignment was skipped; migration between Quarkus versions changing how namespaces are defaulted.

Related errors

• Could not find component reference
• An error occurred while processing ${resourceName}
• Invalid hue, number needs to be between 0 and 360. Defines a
• Invalid saturation, number needs to be between 0 and 100. 0%
• Invalid lightness, number needs to be between 0 and 100. 0%

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