apache/pulsar · error · IllegalArgumentException

failed to initialize %s field while setting value %s

Error message

failed to initialize %s field while setting value %s

What it means

OffloadPoliciesImpl.create(Properties) builds an OffloadPoliciesImpl by reflectively setting each CONFIGURATION_FIELDS field from a properties entry. If f.set fails for any field — value conversion error in the value() helper, a ClassCastException (property value not a String), IllegalArgumentException from the field type, or accessibility issues — it wraps the cause in IllegalArgumentException('failed to initialize <field> field while setting value <value>').

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/policies/data/OffloadPoliciesImpl.java:268

        } else if (driver.equalsIgnoreCase(DRIVER_GOOGLE_CLOUD_STORAGE)) {
            builder.gcsManagedLedgerOffloadRegion(region)
                .gcsManagedLedgerOffloadBucket(bucket)
                .gcsManagedLedgerOffloadMaxBlockSizeInBytes(maxBlockSizeInBytes)
                .gcsManagedLedgerOffloadReadBufferSizeInBytes(readBufferSizeInBytes);
        }

        return builder.build();
    }

    public static OffloadPoliciesImpl create(Properties properties) {
        OffloadPoliciesImpl data = new OffloadPoliciesImpl();
        for (Field f : CONFIGURATION_FIELDS) {
            if (properties.containsKey(f.getName())) {
                try {
                    f.setAccessible(true);
                    f.set(data, value((String) properties.get(f.getName()), f));
                } catch (Exception e) {
                    throw new IllegalArgumentException(
                            String.format("failed to initialize %s field while setting value %s",
                                    f.getName(), properties.get(f.getName())), e);
                }
            }
        }

        Map<String, String> extraConfigurations = getExtraConfigurations(properties);
        if (extraConfigurations != null) {
            data.getManagedLedgerExtraConfigurations().putAll(extraConfigurations);
        }

        data.compatibleWithBrokerConfigFile(properties);
        return data;
    }

    public static OffloadPoliciesImplBuilder builder() {
        return new OffloadPoliciesImplBuilder();
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Read the wrapped cause — it identifies the exact field and conversion problem.
2. Correct the property value's format: numbers must be plain integers, sizes/times use the expected unit format.
3. Ensure all values inserted into Properties are Strings (cast to (String) in create implies String values only).
4. Check for typos against the documented offload configuration keys (s3ManagedLedgerOffread*/azureblob* etc.) — wrong key names are ignored, wrong values fail here.
5. Set the properties programmatically as strings: props.setProperty(key, String.valueOf(value)).

Example fix

// before
props.setProperty("s3ManagedLedgerOffloadMaxBlockSizeInBytes", "64MB"); // wrong format
// after
props.setProperty("s3ManagedLedgerOffloadMaxBlockSizeInBytes", String.valueOf(64 * 1024 * 1024)); // "67108864"

static void validateOffloadProps(Properties props) {
    for (String name : new String[]{"s3ManagedLedgerOffloadMaxBlockSizeInBytes",
                                    "s3ManagedLedgerOffloadReadBufferSizeInBytes",
                                    "managedLedgerOffloadThrottleInBytes"}) {
        String v = props.getProperty(name);
        if (v != null) Long.parseLong(v.trim()); // throws early on bad format
    }
}

try {
    OffloadPoliciesImpl policies = OffloadPoliciesImpl.create(properties);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("failed to initialize")) {
        // e.getCause() names the field and bad value; fix the property value format
    }
    throw e;
}

When it happens

Trigger: Creating offloader policies from a Properties object where a known offload field (e.g. s3ManagedLedgerOffloadRegion, offloadersDirectory, or a numeric/boolean/size field) has a value that cannot be converted to the field's type — e.g. 's3ManagedLedgerOffloadMaxBlockSizeInBytes=abc', a non-String object in the Properties, or a malformed size/time spec.

Common situations: broker.conf / standalone.conf offload settings copied with wrong units or typo'd values; passing Properties read from a config file where numbers are unparsable; mixing typed properties (Integer values) into Properties<String,String>.

Related errors

• Could not instantiate <configKeyName> '<factoryClassName>'
• Cursor %s mark-delete position %s is ahead of the last posit
• Timeout during reset cursor
• Timeout during delete operation
• Timeout during close operation

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/25d2ae1b75db8dcb. Report an issue: GitHub.