pinpoint-apm/pinpoint · error · IllegalStateException

%s load fail Caused by:%s

Error message

%s load fail Caused by:%s

What it means

Thrown by PropertyLoaderUtils.loadFileProperties when reading a properties file as UTF-8 raises IOException. The method wraps the failure into an IllegalStateException including the file path and the cause message, since config loading happens at agent startup and cannot continue without the properties.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/config/PropertyLoaderUtils.java:21

import java.io.BufferedReader;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;

public class PropertyLoaderUtils {

    public static final String[] ALLOWED_PROPERTY_PREFIX = new String[]{"bytecode.", "profiler.", "pinpoint."};

    public static Properties loadFileProperties(Path filePath) {
        Properties properties = new Properties();
        try (BufferedReader reader = Files.newBufferedReader(filePath, StandardCharsets.UTF_8)) {
            properties.load(reader);
        } catch (IOException e) {
            throw new IllegalStateException(String.format("%s load fail Caused by:%s", filePath, e.getMessage()), e);
        }
        return properties;
    }


    public static <K, V> Map<K, V> filterAllowedPrefix(Map<K, V> properties) {
        final Map<K, V> copy = new HashMap<>();
        for (Map.Entry<K, V> entry : properties.entrySet()) {
            final K key = entry.getKey();
            final V value = entry.getValue();
            if (key instanceof String && value instanceof String) {
                final String name = (String) key;
                if (filter(name)) {
                    copy.put(key, value);
                }
            }
        }
        return copy;

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Verify the path exists and is readable: ls -l <file>; fix the path or permissions
  2. Check the cause message in the exception (missing file vs read error vs decode failure)
  3. Re-save the config file as UTF-8 without a BOM
  4. Redeploy the missing config file from the agent distribution

Example fix

// before
Properties p = PropertyLoaderUtils.loadFileProperties(Paths.get("/agent/pinpoint.config")); // file missing
// after
Path cfg = Paths.get("/agent/pinpoint.config");
if (!Files.isRegularFile(cfg)) { throw new IllegalStateException("config missing: " + cfg); }
Properties p = PropertyLoaderUtils.loadFileProperties(cfg);
Defensive patterns

Strategy: validation

Validate before calling

Path cfg = Paths.get(path);
if (!Files.isRegularFile(cfg)) throw new IllegalStateException("config missing: " + cfg);
if (!Files.isReadable(cfg)) throw new IllegalStateException("config unreadable: " + cfg);

Type guard

boolean isReadableFile(Path p) { return Files.isRegularFile(p) && Files.isReadable(p); }

Try / catch

try { props = PropertyLoaderUtils.loadFileProperties(path); } catch (IllegalStateException e) { log.error("properties load failed: {}", e.getMessage(), e.getCause()); throw e; }

Prevention

When it happens

Trigger: Calling loadFileProperties(Path) on a file that does not exist, is a directory, or is unreadable — or on a file with invalid UTF-8 bytes / malformed escapes that make properties parsing fail.

Common situations: Wrong config file path in the agent setup; plugin or profile config renamed/missing after upgrade; non-UTF8 encoded config (GBK/latin-1) saved by an editor; permission changes after deployment.

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