What causes "AI resource import plugin returned null service: {}" in alibaba/nacos?

Fix the offending AiResourceImportServiceBuilder so build() never returns null (throw a descriptive NacosException instead of returning null).

alibaba/nacos · error · NacosApiException

DATA_ACCESS_ERROR

DATA_ACCESS_ERROR

Error message

AI resource import plugin returned null service: {}

What it means

Thrown by AiResourceImportManager.buildImporter() when an AiResourceImportServiceBuilder SPI implementation's build() method returns null. This is a plugin-author defect, not a caller error: the builder advertised itself via SPI but failed to produce a service instance. It is mapped to DATA_ACCESS_ERROR with a SERVER_ERROR top-level code because the server cannot proceed with a usable importer.

Source

Thrown at ai/src/main/java/com/alibaba/nacos/ai/importer/manager/AiResourceImportManager.java:311

    private int resolveMaxItemCount(AiResourceImportServiceBuilder builder) {
        String value =
            builder.getCurrentConfig().get(AiResourceImportConstants.CONFIG_MAX_ITEM_COUNT);
        return StringUtils.isBlank(value) ? AiResourceImportConstants.DEFAULT_MAX_ITEM_COUNT
            : Integer.parseInt(value);
    }
    
    private long resolveMaxArtifactSize(AiResourceImportServiceBuilder builder) {
        String value =
            builder.getCurrentConfig().get(AiResourceImportConstants.CONFIG_MAX_ARTIFACT_SIZE);
        return StringUtils.isBlank(value) ? AiResourceImportConstants.DEFAULT_MAX_ARTIFACT_SIZE
            : Long.parseLong(value);
    }
    
    private AiResourceImportService buildImporter(AiResourceImportServiceBuilder builder)
        throws NacosException {
        AiResourceImportService result = builder.build();
        if (result == null) {
            throw new NacosApiException(NacosException.SERVER_ERROR,
                ErrorCode.DATA_ACCESS_ERROR,
                "AI resource import plugin returned null service: " + builder.pluginName());
        }
        return result;
    }
    
    private void closeImporter(AiResourceImportServiceBuilder builder,
        AiResourceImportService importer, String operation) {
        if (importer == null) {
            return;
        }
        try {
            importer.close();
        } catch (RuntimeException e) {
            LOGGER.warn("Failed to close AI resource import service, pluginName={}, operation={}",
                builder == null ? null : builder.pluginName(), operation, e);
        }
    }

View on GitHub (pinned to 9b989acdf1)

Solutions

Fix the offending AiResourceImportServiceBuilder so build() never returns null (throw a descriptive NacosException instead of returning null).
If you do not own the plugin, remove or disable it via the plugin state checker so resolveBuilder rejects it earlier.
Check the server log for the pluginName in the message and verify the corresponding SPI jar is the intended version and is fully initialized.

Example fix

// before (in your AiResourceImportServiceBuilder)
public AiResourceImportService build() {
    if (client == null) {
        return null; // triggers DATA_ACCESS_ERROR
    }
    return new MyImportService(client);
}

// after
public AiResourceImportService build() throws NacosException {
    if (client == null) {
        throw new NacosException(NacosException.SERVER_ERROR,
            "MyImport client not initialized for plugin " + pluginName());
    }
    return new MyImportService(client);
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    manager.search(request);
} catch (NacosApiException e) {
    if (ErrorCode.DATA_ACCESS_ERROR.getCode() == e.getDetailErrCode()
        && e.getErrMsg().contains("returned null service")) {
        // plugin defect: disable source and alert the plugin owner
        log.error("Import plugin {} is broken, returning null service", sourceId, e);
    }
    throw e;
}

Prevention

In your own AiResourceImportServiceBuilder, never return null from build(); throw a descriptive NacosException instead.
Add a unit test asserting build() returns a non-null service for all builder configurations.
During plugin rollout, call listSources first; a builder that throws on build will only fail on first use, so smoke-test search against each plugin.

When it happens

Trigger: Any AI resource import operation (search, validate, execute) that resolves a managed plugin whose builder.build() returns null. Happens immediately after resolveBuilder succeeds and before any external source is contacted.

Common situations: A custom AiResourceImportServiceBuilder whose build() short-circuits on missing internal state (e.g. credentials not injected, downstream client constructor threw and was swallowed); a third-party plugin jar on the classpath that is partially implemented; a plugin built against an older API where build() was allowed to return null.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/9afe54f72bb6c3a3. Report an issue: GitHub.