DynamoDB Local: Failed to load native library sqlite4java

요약 — DynamoDB Local의 스토리지 엔진은 시작 시 네이티브 라이브러리(sqlite4java)를 로드하는데, JVM이 그것을 찾지 못하거나 실행하지 못합니다. 두 가지 고전적 원인: -Djava.library.path=./DynamoDBLocal_lib 없이 jar를 실행했거나, Apple Silicon Mac인데 번들된 바이너리가 x86_64용입니다. JVM을 네이티브 라이브러리 폴더로 가리키거나, 최신 DynamoDB Local로 업데이트하거나, 멀티 아키텍처 Docker 이미지를 실행하세요.

무엇을 의미하나요

Failed to load native library:'libsqlite4java-osx-1.0.392.dylib'. ...
java.lang.UnsatisfiedLinkError: no sqlite4java-osx-x86_64-1.0.392 in java.library.path

DynamoDB Local은 디스크 스토리지가 네이티브(OS별, 아키텍처별) 라이브러리로 뒷받침되는 Java 애플리케이션입니다. UnsatisfiedLinkError는 JVM이 그 바이너리를 링크할 수 없다는 뜻입니다 — 라이브러리 경로에 아예 없거나, 파일은 존재하지만 JVM과 다른 OS/CPU 아키텍처용으로 빌드되었습니다. 그것 없이는 에뮬레이터가 시작할 수 없습니다.

왜 발생하나요

-Djava.library.path 누락 — 다운로드는 네이티브를 DynamoDBLocal_lib/에 제공하며, 문서화된 실행 명령이 JVM을 그곳으로 가리켜야 합니다. java -jar DynamoDBLocal.jar를 그냥(또는 다른 작업 디렉터리에서) 실행하면 그것들을 잃습니다.
Apple Silicon(M 시리즈) + x86_64 네이티브 — 오래된 DynamoDB Local 빌드와 래퍼는 Intel libsqlite4java-osx 바이너리만 번들합니다. ARM64 JVM은 그것들을 로드하기를 거부합니다("no matching architecture").
오래된 복사본을 고정하는 래퍼 — jest-dynamodb, serverless-dynamodb-local 등 유사 도구는 자체 DynamoDB Local을 다운로드합니다. 캐시된 오래된 버전은 "업데이트" 후에도 낡은 네이티브를 유지합니다.
정리된 임시 디렉터리로 추출된 네이티브 — 일부 설정은 OS가 지우는 임시 폴더로 압축을 풀어, 재부팅 전까지는 작동합니다.

어떻게 고치나요

추출된 폴더에서 문서화된 방식으로 실행하세요:

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

DynamoDB Local을 업데이트하세요 — 최신 릴리스를 다운로드하세요. 새 빌드는 오래된 것을 괴롭혔던 Apple Silicon 상황을 해결합니다. 래퍼가 설치를 관리한다면 캐시를 지우거나 재설치해 실제로 새 버전을 가져오게 하세요.
또는 Docker로 네이티브를 완전히 우회하세요 — amazon/dynamodb-local 이미지가 가장 취약하지 않은 경로이며 Apple Silicon에서 실행됩니다:
```
docker run -p 8000:8000 amazon/dynamodb-local
```
변경할 수 없는 오래된 빌드의 Apple Silicon에서는: Rosetta 2 아래에서 x86_64 JDK를 실행하거나(그러면 Intel 네이티브가 JVM과 일치), libsqlite4java-osx.dylib를 커뮤니티에서 배포한 sqlite4java의 ARM64 빌드로 교체하세요.
인메모리 탈출구: -inMemory도 현재 빌드에서는 라이브러리가 필요합니다 — 누락된 네이티브의 우회책이 아닙니다. 대신 경로/아키텍처를 고치세요.

에뮬레이터가 실행되면 도구를 그것으로 가리키세요 — DynoTable 데스크톱 앱은 http://localhost:8000에서 DynamoDB Local에 연결하므로 스크립트를 작성하지 않고도 테이블을 만들고 데이터를 검사할 수 있습니다. DynamoDB JSON 변환기로 시드 항목을 와이어 형식으로 준비하세요.

References

Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (the documented java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar launch command)
DynamoDB local usage notes — AWS DynamoDB Developer Guide (-sharedDb, -inMemory and the other runtime options)
amazon/dynamodb-local — Docker Hub (official multi-architecture image — amd64 + arm64, so it runs natively on Apple Silicon)

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

DynamoDB Local: Failed to load native library sqlite4java

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References