apache/dubbo · error · IllegalStateException

Failed to load <resolveFile>, cause: <e.getMessage()>

Error message

Failed to load <resolveFile>, cause: <e.getMessage()>

What it means

Thrown by ReferenceConfigBase.resolveFile when the configured dubbo-resolve.properties file exists and is referenced but cannot be opened or read (IOException wrapped in IllegalStateException). The resolve file provides point-to-point URL overrides for specific interfaces, bypassing the registry.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/config/ReferenceConfigBase.java:329

    protected void resolveFile() {
        String resolve = System.getProperty(interfaceName);
        String resolveFile = null;
        if (StringUtils.isEmpty(resolve)) {
            resolveFile = SystemPropertyConfigUtils.getSystemProperty(CommonConstants.DubboProperty.DUBBO_RESOLVE_FILE);
            if (StringUtils.isEmpty(resolveFile)) {
                File userResolveFile = new File(
                        new File(SystemPropertyConfigUtils.getSystemProperty(USER_HOME)), "dubbo-resolve.properties");
                if (userResolveFile.exists()) {
                    resolveFile = userResolveFile.getAbsolutePath();
                }
            }
            if (resolveFile != null && resolveFile.length() > 0) {
                Properties properties = new RegexProperties();
                try (FileInputStream fis = new FileInputStream(resolveFile)) {
                    properties.load(fis);
                } catch (IOException e) {
                    throw new IllegalStateException("Failed to load " + resolveFile + ", cause: " + e.getMessage(), e);
                }

                resolve = properties.getProperty(interfaceName);
            }
        }
        if (StringUtils.isNotEmpty(resolve)) {
            url = resolve;
            if (logger.isWarnEnabled()) {
                if (resolveFile != null) {
                    logger.warn(
                            COMMON_UNEXPECTED_EXCEPTION,
                            "",
                            "",
                            "Using default dubbo resolve file " + resolveFile + " replace " + interfaceName + ""
                                    + resolve + " to p2p invoke remote service.");
                } else {
                    logger.warn(
                            COMMON_UNEXPECTED_EXCEPTION,

View on GitHub (pinned to 3a3043227f)

Solutions

1. Check the resolve file's permissions and ensure the application user can read it.
2. Confirm the path is a regular file, not a directory or dead symlink.
3. Remove or fix the -Ddubbo.resolve.file system property / the ~/dubbo-resolve.properties file if point-to-point override is not intended.

Example fix

# before
$ chmod 000 ~/dubbo-resolve.properties

# after
$ chmod 644 ~/dubbo-resolve.properties

// Pre-check the resolve file is readable before triggering resolveFile()
String resolveFile = SystemPropertyConfigUtils.getSystemProperty(
    CommonConstants.DubboProperty.DUBBO_RESOLVE_FILE);
if (resolveFile != null && !resolveFile.isEmpty()) {
    File f = new File(resolveFile);
    if (!f.isFile() || !f.canRead()) {
        throw new IllegalStateException("dubbo-resolve file not readable: " + f.getAbsolutePath());
    }
}

try {
    // resolveFile() is invoked internally during reference init
    referenceConfig.get();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to load ")) {
        // fix permissions/path of the dubbo-resolve.properties file, then retry
    }
    throw e;
}

When it happens

Trigger: resolveFile() locates a resolve file (via -Ddubbo.resolve.file or ~/.dubbo-resolve.properties) but FileInputStream/Properties.load throws IOException — e.g. file permissions, file is a directory, or it became unreadable between the exists() check and load.

Common situations: dubbo-resolve.properties has wrong permissions (not readable by the app user). The path points to a directory or a broken symlink. File removed or locked by another process between exists() and load(). Container/sandbox environments with restricted home-directory access.

Related errors

• Mark buffer is full!
• should mark before reset!
• Negative initial size: ${size}
• Read-ahead limit < 0
• Stream closed

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/6c898cf656825f20. Report an issue: GitHub.