quarkusio/quarkus · error · RuntimeException

Could not find component reference

Error message

Could not find component reference

What it means

Card.getComponentRef() builds the web-component path (./../<namespace>/<componentLink>) used by the Dev UI to render this card. The library throws because a Card was created with a null namespace and no fallback 'not found' component exists yet, so no valid component reference can be computed.

Source

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

    private final String componentLink; // This is a link to the component, excluding namespace
    private String namespace; // The namespace (a.k.a extension path)

    public Card(String componentLink) {
        if (componentLink.endsWith(DOT_JS)) {
            this.componentLink = componentLink;
        } else {
            this.componentLink = componentLink + DOT_JS;
        }

        this.componentName = this.componentLink.substring(0, this.componentLink.length() - 3);
    }

    public String getComponentRef() {
        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 void setNamespace(String namespace) {
        this.namespace = namespace;
    }

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

    public String getComponentLink() {
        return componentLink;
    }

    public String getComponentName() {
        return componentName;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Set the namespace on the Card before rendering, e.g. card.setNamespace("org.acme") so the ref resolves to ./../org.acme/<componentLink>
2. If the card is internal to Dev UI, use the Page-based builder (which handles the qwc internal namespace) instead of a raw Card
3. Verify the extension's Dev UI page builder chain (PageBuilder.namespace(...) or WebComponentPageBuilder) actually passes a namespace
4. Upgrade Quarkus: newer versions may provide the planned not-found component instead of throwing

Example fix

// before
Card card = new Card();
card.setComponentLink("qwc-foo-card.js");
String ref = card.getComponentRef(); // throws
// after
Card card = new Card();
card.setNamespace("org.acme");
card.setComponentLink("qwc-foo-card.js");
String ref = card.getComponentRef(); // ./../org.acme/qwc-foo-card.js

if (card.getNamespace() == null || card.getNamespace().isBlank()) {
    throw new IllegalStateException("Card namespace must be set before computing component ref: " + card);
}

boolean hasComponentRef(Card c) {
    return c != null && c.getNamespace() != null && !c.getNamespace().isBlank();
}

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

When it happens

Trigger: Calling getComponentRef() on a Card whose namespace field was never set via setNamespace() (or a builder path that never assigned it) while the card still has a componentLink.

Common situations: Extension authors building custom Dev UI cards programmatically or via JSON-EJB/recorded pages and forgetting to set the namespace; cards deserialized from configuration missing the namespace field; upstream refactors that moved components between namespaces leaving stale card definitions.

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/c6679803cd60ea48. Report an issue: GitHub.