pinpoint-apm/pinpoint · error · IllegalStateException

%s load fail Caused by:%s

Error message

%s load fail Caused by:%s

What it means

loadFileProperties loads a key=value properties file into a Properties object via Files.newInputStream. If an IOException occurs while opening/reading the file, it wraps the cause in an IllegalStateException with '<path> load fail Caused by:<message>'.

Source

Thrown at agent-module/agent-tools/src/main/java/com/navercorp/pinpoint/tools/NetworkAvailabilityChecker.java:111

        }

        try {
            checkGRPCSpan(grpcTransportConfig);
        } catch (Exception e) {
            e.printStackTrace();
        }

    }

    private static String getActiveProfile(Properties defaultProperties) {
        return defaultProperties.getProperty(ACTIVE_PROFILE_KEY, DEFAULT_PROFILE);
    }

    private static void loadFileProperties(Properties properties, Path filePath) {
        try (InputStream inputStream = Files.newInputStream(filePath)) {
            properties.load(inputStream);
        } catch (IOException e) {
            throw new IllegalStateException(String.format("%s load fail Caused by:%s", filePath, e.getMessage()), e);
        }
    }

    private static void checkGRPCBase(GrpcTransportConfig grpcTransportConfig) throws Exception {
        String ip = grpcTransportConfig.getAgentCollectorIp();
        int port = grpcTransportConfig.getAgentCollectorPort();

        NetworkChecker checker = new TCPChecker("TCP Base", ip, port);
        checker.check();
    }

    private static void checkGRPCMeta(GrpcTransportConfig grpcTransportConfig) throws Exception {
        String ip = grpcTransportConfig.getMetadataCollectorIp();
        int port = grpcTransportConfig.getMetadataCollectorPort();

        NetworkChecker checker = new TCPChecker("TCP Meta", ip, port);
        checker.check();
    }

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Verify the file path exists and is readable before running
  2. Fix the path passed to the checker in your command/config
  3. Re-save the properties file as ISO-8859-1/UTF-8 without BOM
  4. Check file permissions and that the path is a regular file

Example fix

// before
java ... NetworkAvailabilityChecker -config ./conf/props
// after
ls -l conf/checker.properties && java ... NetworkAvailabilityChecker -config conf/checker.properties
Defensive patterns

Strategy: try-catch

Validate before calling

Path p = Path.of(configPath);
if (!Files.isRegularFile(p) || !Files.isReadable(p)) throw new IllegalArgumentException("Properties file missing or unreadable: " + p);

Try / catch

try { checker.run(propsPath); } catch (IllegalStateException e) { if (e.getMessage().contains("load fail")) { log.error("Check properties path/encoding: {}", propsPath); } throw e; }

Prevention

When it happens

Trigger: main passes a properties file path that does not exist, is a directory, is locked, or has bad encoding, so Files.newInputStream or properties.load throws IOException.

Common situations: Wrong -D config path when running NetworkAvailabilityChecker, file not copied into the working directory, permission issues, or a corrupted/UTF-16 encoded properties file causing MalformedInput IOException.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/7b66c4c3e02efeae. Report an issue: GitHub.