Document version.properties file to avoid warnings

[epomatti]

I've noticed this warning message when calling ParamManager.getSecretsProvider():

Unable to read version.properties file. Using default version.

This is the full log message:

{"timestamp":"2025-03-22T14:28:18.815+0000GMT","instant":{"epochSecond":1742653698,"nanoOfSecond":815974806},"thread":"main","level":"WARN","loggerName":"software.amazon.lambda.powertools.core.internal.UserAgentConfigurator","message":"Unable to read version.properties file. Using default version.","endOfBatch":false,"loggerFqcn":"org.apache.logging.slf4j.Log4jLogger","threadId":1,"threadPriority":5,"coldStart":"true","functionArn":"arn:aws:lambda:us-east-1:012345678912:function:SQSFunction","functionMemorySize":"512","functionName":"SQSFunction","functionVersion":"$LATEST","function_request_id":"938a96f5-d55e-45d4-99d2-3f1d6db2c005","samplingRate":"0.0","service":"service_undefined"}

I was able to suppress the warning by creating an empty version.properties file, as in my case I don't need to specify the powertools.version, default is fine. Here's a link to the related code:

powertools-lambda-java/powertools-core/src/main/java/software/amazon/lambda/powertools/core/internal/UserAgentConfigurator.java

Lines 67 to 83 in 7434bf9

	static String getVersionFromProperties(String propertyFileName, String versionKey) {
	URL propertiesFileURI = Thread.currentThread().getContextClassLoader().getResource(propertyFileName);
	if (propertiesFileURI != null) {
	try (FileInputStream fis = new FileInputStream(propertiesFileURI.getPath())) {
	Properties properties = new Properties();
	properties.load(fis);
	String version = properties.getProperty(versionKey);
	if (version != null && !version.isEmpty()) {
	return version;
	}
	} catch (IOException e) {
	LOG.warn("Unable to read {} file. Using default version.", propertyFileName);
	LOG.debug("Exception:", e);
	}
	}
	return NA;

I tried searching the documentation but couldn't find any guides about the version.properties other what has been documented in the code. Because this behavior is generating a warning, perhaps a short reference in the documentation would help others find the solution more quickly.

[phipag]

Hey @epomatti, thank you for reporting this. I tried to reproduce your behavior but I don't see any warning in my logs. The version.properties file was introduced as part of #1274.

It adds a user-agent header to the SDK calls made by Powertools and the version number read by the UserAgentConfigurator will be added to the version.properties file at build-time included in the powertools-core dependency.

Ideally, you should not create a version.properties file at all since it will be included automatically. Would you mind sharing more details about your code / system setup?

Ideally, you should see version.properties file if you unzip the dependency at target/lib/software.amazon.lambda.powertools-metrics-1.19.0.jar

[epomatti]

Hi @phipag I was thinking that could be the case but didn't look more into it.

I was able to reproduce the error with this minimal code.

package io.pomatti.lambda;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import com.amazonaws.services.lambda.runtime.events.SQSEvent;
import software.amazon.lambda.powertools.parameters.ParamManager;

import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import software.amazon.lambda.powertools.logging.Logging;

public class Function implements RequestHandler<SQSEvent, Void> {

  Logger log = LogManager.getLogger(Function.class);

  @Logging
  @Override
  public Void handleRequest(SQSEvent sqsEvent, Context context) {
    ParamManager.getSecretsProvider();
    return null;
  }

}

plugins {
    id 'java'
    id 'io.freefair.aspectj.post-compile-weaving' version '8.13'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.amazonaws:aws-lambda-java-core:1.2.3'
    implementation 'com.amazonaws:aws-lambda-java-events:3.15.0'
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.12.1'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.12.1'
    aspect 'software.amazon.lambda:powertools-logging:1.19.0'
    aspect 'software.amazon.lambda:powertools-tracing:1.19.0'
    aspect 'software.amazon.lambda:powertools-metrics:1.19.0'
    aspect 'software.amazon.lambda:powertools-parameters:1.19.0'
    runtimeOnly 'org.aspectj:aspectjrt:1.9.23'
}

sourceCompatibility = 21
targetCompatibility = 21

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <Console name="JsonAppender" target="SYSTEM_OUT">
            <JsonTemplateLayout eventTemplateUri="classpath:LambdaJsonLayout.json" />
        </Console>
    </Appenders>
    <Loggers>
        <Logger name="JsonLogger" level="INFO" additivity="false">
            <AppenderRef ref="JsonAppender"/>
        </Logger>
        <Root level="info">
            <AppenderRef ref="JsonAppender"/>
        </Root>
    </Loggers>
</Configuration>

[phipag]

Hey @epomatti, thanks for sharing the code example. I was able to reproduce this issue now and also found the problem.

The offending code line is this line.

URL propertiesFileURI = Thread.currentThread().getContextClassLoader().getResource(propertyFileName);

Since the version.properties file is bundled in the JAR it is not possible to read it as a regular file. There are some related StackOverlow posts – this one for example.

We already fixed this in the code for the upcoming new major version v2 where we read the properties file as resource input stream instead. See the new method: https://github.com/aws-powertools/powertools-lambda-java/blob/v2/powertools-common/src/main/java/software/amazon/lambda/powertools/common/internal/UserAgentConfigurator.java#L66-L84.

InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(propertyFileName);

I will convert this discussion to an issue and will also a release a fix for the current version v1 while work on v2 is being continued.

[phipag]

I created an issue for this: #1812

[phipag]

Hey @epomatti, I created a PR to fix this: #1813

Do you mind checking out this PR in your local workspace and confirm if this resolves the issue for you?

I tested it in my stack and the warning is gone.

[epomatti]

I was able to test it locally and it seems to be OK now; no warning was logged.

Here's what I did:

1. Checked out the phipag/issue1812 branch
2. Compiled and installed it locally with mvn -B install --file pom.xml
3. Deleted the version.properties workaround file from my project resources
4. Added mavenLocal() and changed the versions to 1.20.0

LGTM

[phipag]

Awesome, thanks for testing this @epomatti! I will merge the PR and it will be included with the next release.

[phipag]

Hey @epomatti,

just letting you know that I released the fix for this in version 1.20.1 today: https://github.com/aws-powertools/powertools-lambda-java/releases/tag/v1.20.1.

Thanks again for your input!

[epomatti]

Appreciate it, I'll update that to my code