Introduction

Spring Boot displays a banner on startup from banner.txt, but when the file encoding does not match the console encoding, or when JVM default encoding is not UTF-8, special characters (UTF-8 art, non-ASCII text) display as garbled text or question marks. This is common in Docker containers where the default locale is POSIX with ASCII encoding, in Windows environments where the default is Cp1252, and in CI/CD pipelines where terminal encoding is not configured. While banner encoding issues are cosmetic, they indicate a broader encoding misconfiguration that can affect log messages, file I/O, and HTTP request handling.

Symptoms

bash
?????????????????????????
  ?  Spring Boot ?       ?
  ?????????????????????????
# UTF-8 art characters displayed as ? or □

Or:

bash
██████████
# UTF-8 bytes interpreted as wrong encoding

Common Causes

  • JVM default encoding not UTF-8: -Dfile.encoding not set
  • banner.txt saved with wrong encoding: File saved as Latin-1 or Windows-1252
  • Docker container lacks locale: No LANG environment variable set
  • Console does not support UTF-8: Terminal emulator encoding mismatch
  • Maven resource filtering corrupts file: Maven copies banner.txt with wrong encoding
  • Git line ending conversion: CRLF conversion corrupts multi-byte characters

Step-by-Step Fix

Step 1: Set JVM encoding to UTF-8

```bash # JVM flag java -Dfile.encoding=UTF-8 -jar myapp.jar

# Or in Dockerfile ENV JAVA_OPTS="-Dfile.encoding=UTF-8" ENTRYPOINT java $JAVA_OPTS -jar /app/myapp.jar ```

Step 2: Configure banner file correctly

_ \ __ _ _ ___ ___ / ___
/ _`'_ \__/ _ \
_(_(_)
____/ \__,___\__\___/ \____

${AnsiColor.BRIGHT_GREEN} Application Version: ${application.version} Spring Boot Version: ${spring-boot.version} ${AnsiColor.DEFAULT} ```

Step 3: Configure Maven and Docker for UTF-8

```xml <!-- pom.xml --> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> </properties>

<build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-resources-plugin</artifactId> <configuration> <encoding>UTF-8</encoding> <nonFilteredFileExtensions> <!-- Do not filter banner files --> <nonFilteredFileExtension>txt</nonFilteredFileExtension> </nonFilteredFileExtensions> </configuration> </plugin> </plugins> </build> ```

dockerfile
# Dockerfile
FROM eclipse-temurin:17-jre
ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8
ENV JAVA_OPTS="-Dfile.encoding=UTF-8"

Prevention

  • Always set -Dfile.encoding=UTF-8 in JVM arguments
  • Configure project.build.sourceEncoding=UTF-8 in Maven/Gradle
  • Set LANG=C.UTF-8 in Docker images
  • Save banner.txt as UTF-8 in your editor
  • Add encoding checks to CI that verify file encodings
  • Use Spring Boot's AnsiColor placeholders for terminal-safe color output
  • Test startup output in the same environment where the application runs