DynamoDB Local: Failed to load native library sqlite4java

TL;DR — Storage engine DynamoDB Local memuat native library (sqlite4java) saat startup, dan JVM entah tidak dapat menemukannya atau tidak dapat menjalankannya. Dua penyebab klasik: Anda meluncurkan jar tanpa -Djava.library.path=./DynamoDBLocal_lib, atau Anda di Mac Apple Silicon dan binary yang dibundel untuk x86_64. Arahkan JVM ke folder native-lib, perbarui ke DynamoDB Local terkini, atau jalankan image Docker multi-arch.

Apa artinya

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 adalah aplikasi Java yang penyimpanan on-disk-nya didukung oleh native library (per-OS, per-arsitektur). UnsatisfiedLinkError adalah JVM mengatakan ia tidak dapat menautkan binary itu — entah ia tidak ada di library path sama sekali, atau file ada tetapi dibangun untuk OS/arsitektur CPU yang berbeda dari JVM Anda. Emulator tidak dapat memulai tanpanya.

Mengapa terjadi

-Djava.library.path hilang — unduhan mengirim native di DynamoDBLocal_lib/, dan perintah peluncuran yang didokumentasikan harus mengarahkan JVM ke sana. Menjalankan java -jar DynamoDBLocal.jar telanjang (atau dari direktori kerja berbeda) kehilangan mereka.
Apple Silicon (seri M) + native x86_64 — build dan pembungkus DynamoDB Local lama hanya membundel binary Intel libsqlite4java-osx; JVM ARM64 menolak memuatnya ("no matching architecture").
Pembungkus yang menyematkan salinan lama — jest-dynamodb, serverless-dynamodb-local, dan alat serupa mengunduh DynamoDB Local-nya sendiri; versi lama yang di-cache mempertahankan native usang bahkan setelah Anda "memperbarui".
Native diekstrak ke direktori temp yang dibersihkan — beberapa setup membongkar ke folder temp yang dibersihkan OS, jadi berfungsi sampai reboot.

Cara memperbaikinya

Luncurkan dengan cara yang didokumentasikan, dari folder yang diekstrak:

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

Perbarui DynamoDB Local — unduh rilis terkini; build yang lebih baru menyelesaikan situasi Apple Silicon yang mengganggu yang lama. Jika pembungkus mengelola instalasi, bersihkan cache-nya/instal ulang agar benar-benar mengambil versi baru.
Atau hindari native sepenuhnya dengan Docker — image amazon/dynamodb-local adalah jalur paling tidak rapuh dan berjalan di Apple Silicon:
```
docker run -p 8000:8000 amazon/dynamodb-local
```
Di Apple Silicon dengan build lama yang tidak dapat Anda ubah: jalankan JDK x86_64 di bawah Rosetta 2 (native Intel kemudian cocok dengan JVM), atau ganti libsqlite4java-osx.dylib dengan build ARM64 sqlite4java yang dipublikasikan komunitas.
Escape hatch in-memory: -inMemory tetap membutuhkan library di build terkini — ini bukan solusi untuk native yang hilang; perbaiki path/arch sebagai gantinya.

Setelah emulator aktif, arahkan alat Anda ke sana — aplikasi desktop DynoTable terhubung ke DynamoDB Local di http://localhost:8000 sehingga Anda dapat membuat tabel dan memeriksa data tanpa menulis skrip. Gunakan DynamoDB JSON converter untuk menyiapkan item seed dalam format wire.

Kesalahan terkait

Unable to start DynamoDB Local process — kegagalan startup payung yang sering menyembunyikan ini di dalamnya.
DynamoDB Local port 8000 in use
Could not connect to DynamoDB Local
Pelajari: Running DynamoDB Local

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)

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.