apache/druid · error · IllegalStateException

Invalid value start byte

Error message

Invalid value start byte [%s]

What it means

Each value in a string field must begin with a known kind byte (e.g. NULL_BYTE or NOT_NULL_BYTE). When addStringsToList reads a kind byte outside the recognized set, the field encoding is not what the reader expects, and it throws ISE. This means the bytes are not a validly encoded string/string-array field.

Solutions

1. Re-generate or re-fetch the frame to rule out corruption.
2. Align reader and writer on the same Druid version / frame format version.
3. Confirm the field is actually a string/string-array field before invoking addStringsToList.

try {
  reader.readStringsFromMemory(memory, position, limit, list);
} catch (IllegalStateException e) {
  if (e.getMessage().startsWith("Invalid value start byte")) {
    throw new CorruptFrameException("Field encoding mismatch; likely version skew", e);
  }
  throw e;
}

When it happens

Trigger: Decoding memory with an invalid first byte per value — frames written by a different serializer version, offsets misaligned by earlier bad decoding, or wrapping arbitrary bytes as a string field.

Common situations: Version skew between writer and reader of frame format; reading a non-string field as a string field; corrupted durable storage frames after crash.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Value overrun
• Unexpected end of field
• A-Not-B requires at least 1 sketch
• Access-Check-Result
• Action [ ] failed for worker [ ] with status ( )

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/e0c40cac1555a0b5. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/frame/field/StringFieldReader.java:599

            final byte b = memory.getByte(i);

            if (b == StringFieldWriter.VALUE_TERMINATOR) {
              final int len = Ints.checkedCast(i - position);

              final ByteBuffer buf = FrameReaderUtils.readByteBuffer(memory, position, len);
              list.add(buf);

              position += len;

              break;
            }
          }

          break;

        default:
          throw new ISE("Invalid value start byte [%s]", kind);
      }
    }

    if (!rowTerminatorSeen) {
      throw new ISE("Unexpected end of field");
    }
    return isEffectivelyNull;
  }
}

View on GitHub (pinned to 9b90983fd2)