What causes "UTF ERROR [\"%s\":%d]: %s\n" in openjdk/jdk?

Set a full locale in the container: ENV LANG=C.UTF-8 (and install the locale package)

UTF ERROR [\"%s\":%d]: %s\n

Error message

UTF ERROR [\"%s\":%d]: %s\n

What it means

Fatal error handler in the Unix encoding support for libinstrument: an iconv-based UTF-8/platform-encoding conversion failed (bad descriptor, incomplete byte sequence, or iconv_open failure for the platform codeset). The handler prints the file/line and message, then calls abort(), immediately terminating the JVM with SIGABRT.

Source

Thrown at src/java.instrument/unix/native/libinstrument/EncodingSupport_md.c:51

/* Routines to convert back and forth between Platform Encoding and UTF-8 */

/* Error and assert macros */
#define UTF_ERROR(m) utfError(__FILE__, __LINE__,  m)
#define UTF_ASSERT(x) ( (x)==0 ? UTF_ERROR("ASSERT ERROR " #x) : (void)0 )
#define UTF_DEBUG(x)

/* Global variables */
static iconv_t iconvToPlatform          = (iconv_t)-1;
static iconv_t iconvFromPlatform        = (iconv_t)-1;

/*
 * Error handler
 */
static void
utfError(char *file, int line, char *message)
{
    (void)fprintf(stderr, "UTF ERROR [\"%s\":%d]: %s\n", file, line, message);
    abort();
}

/*
 * Initialize all utf processing.
 */
static void
utfInitialize(void)
{
    const char* codeset;

#ifndef MACOSX
    /* Set the locale from the environment */
    (void)setlocale(LC_ALL, "");

    /* Get the codeset name */
    codeset = (char*)nl_langinfo(CODESET);
    if ( codeset == NULL || codeset[0] == 0 ) {

View on GitHub (pinned to 88dfb74bbe)

Solutions

Set a full locale in the container: ENV LANG=C.UTF-8 (and install the locale package)
Keep agent jar paths pure ASCII to avoid platform-encoding conversion entirely
Use a base image that ships complete glibc/iconv data (e.g. full debian/ubuntu JDK images rather than stripped ones)
Check the printed file/line to see which conversion direction failed and validate that string's encoding

Example fix

# before (Dockerfile)
FROM distroless-base
ENV LANG=C
# after
FROM ubuntu:24.04
ENV LANG=C.UTF-8 LC_ALL=C.UTF-8

Defensive patterns

Strategy: validation

Validate before calling

// fail fast if the platform charset cannot round-trip agent paths
Charset.defaultCharset();
byte[] b = agentPath.getBytes(StandardCharsets.UTF_8);
if (!new String(b, StandardCharsets.UTF_8).equals(agentPath))
    throw new IllegalStateException("agent path not round-trippable in UTF-8");

Prevention

Set LANG=C.UTF-8 in container images running instrumented JVMs
Use base images with complete glibc/iconv locale data
Keep agent jar paths ASCII-only to sidestep platform encoding entirely

When it happens

Trigger: utf8ToPlatform/platformToUtf8 conversions failing: agent jar paths or class names containing byte sequences invalid in the platform locale; iconv_open unable to load the platform codeset (missing locale data, e.g. minimal container images); iconv descriptor closed/invalid after initialization failure.

Common situations: Running instrumented JVMs in slim Docker images without glibc locale data (POSIX/C locale with non-ASCII paths); agent jar paths with unusual Unicode; Alpine/musl-based images with incomplete iconv support.

Related errors

AI-assisted analysis of openjdk/jdk@88dfb74bbe (2026-08-14). Data as JSON: /api/errors/f27c070453f1295e. Report an issue: GitHub.