DynamoDB Local: UnsupportedClassVersionError

요약 — Java 런타임이 DynamoDB Local이 컴파일된 것보다 오래되었습니다. 최신 DynamoDB Local(v2.6.0 이상, v3.x 포함)은 JRE 17+ 가 필요하며 — Java 8/11에서 실행하면 JVM이 UnsupportedClassVersionError로 클래스 파일을 거부합니다. Java 17+ 런타임(Temurin, Corretto 등)을 설치하고 다시 실행하거나, amazon/dynamodb-local Docker 이미지로 로컬 Java를 완전히 건너뛰세요.

무엇을 의미하나요

Error: A JNI error has occurred...
java.lang.UnsupportedClassVersionError: com/amazonaws/services/dynamodbv2/local/main/ServerRunner
has been compiled by a more recent version of the Java Runtime
(class file version 61.0), this version of the Java Runtime only
recognizes class file versions up to 52.0

숫자가 불일치를 해독합니다: 클래스 파일 버전 61은 Java 17, 52는 Java 8입니다. jar의 바이트코드는 PATH의 java보다 새로운 JVM을 대상으로 하므로, JVM이 DynamoDB Local이 한 줄이라도 실행하기 전에 중단됩니다. AWS는 하한선을 명시적으로 문서화합니다: v2.6.0+는 17보다 오래된 JRE에서 실행되지 않습니다.

왜 발생하나요

시스템 java가 여전히 8 또는 11 — 오래된 CI 이미지와 몇 년 전에 LTS JDK가 설치된 머신에서 흔합니다.
JAVA_HOME/PATH가 오래된 JDK를 가리킴 — 새 JDK가 설치되었지만 셸이 레거시를 먼저 해석합니다.
DynamoDB Local 업그레이드가 요구 사항을 넘음 — 1.x jar는 Java 8에서 실행되었습니다. 이를 2.x/3.x로 교체하면 조용히 하한선을 17로 올립니다.
빌드 도구가 툴체인을 고정 — 오래된 툴체인으로 구성된 Maven/Gradle이 임베디드 DynamoDB Local을 그 아래에서 실행합니다.

어떻게 고치나요

실제로 실행 중인 것을 확인하세요:
```
java -version
```

Java 17+ 런타임을 설치하고(어느 배포판이든 — Eclipse Temurin, Amazon Corretto 등) 셸을 그것으로 가리키세요:

export JAVA_HOME=/path/to/jdk-17
export PATH="$JAVA_HOME/bin:$PATH"
java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

또는 로컬 Java 요구 사항을 없애세요 — Docker 이미지는 호환되는 런타임을 제공합니다:
```
docker run -p 8000:8000 amazon/dynamodb-local
```
CI 이미지와 툴체인을 업데이트하세요 — DynamoDB Local이 시작되는 모든 곳에 Java 17+를 고정하세요(테스트 러너, Maven/Gradle 툴체인). 그러면 오류가 머신마다 다시 나타나지 않습니다.

포트 8000에서 부팅되면 도구를 http://localhost:8000으로 가리키세요 — DynoTable 데스크톱 앱은 DynamoDB Local에 일급 엔드포인트로 연결하고, DynamoDB Expression Builder는 그것에 대해 실행할 쿼리를 작성합니다.

References

Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (the JRE 17+ requirement for v2.6.0+, launch command, version listing)
DynamoDB local usage notes — AWS DynamoDB Developer Guide (-sharedDb and the other runtime options)
amazon/dynamodb-local — Docker Hub (official image bundles a compatible Java runtime)

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.

DynamoDB Local: UnsupportedClassVersionError

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References