Masalah module adalah kelas galat yang paling sering menghentikan pemula Go: import tidak ketemu, checksum cocok tidak, atau versi dependency “aneh”. Kabar baiknya, go tooling merancang pesan galatnya secara deskriptif — kalau kita tahu cara membacanya. Chapter ini menyusun tabel masalah → gejala → solusi, menjelaskan cara kerja resolusi versi MVS, dan menutup dengan dua demo nyata yang dijalankan langsung di lingkungan Go 1.27.

Masalah Module Paling Umum #

Sebelas masalah berikut menutup hampir semua kejadian sehari-hari. Cari gejalanya di kolom tengah, lalu terapkan solusinya:

MasalahGejala di terminalSolusi
Module tidak ditemukanno required module provides package ...Perbaiki path import (typo), lalu go get <path>
Versi tidak resolve via proxygalat unduh dari proxy.golang.orgGOPROXY=direct go mod tidy untuk ambil langsung
Checksum tidak cocokchecksum mismatch di go.sumgo mod tidy; modul privat: set GOPRIVATE
Import cycleimport cycle not allowedPindahkan tipe bersama ke package ketiga
Entry go.sum hilangmissing go.sum entrygo mod tidy atau go mod download <modul>
Versi ganda (MVS)versi terpilih tak sesuai harapango list -m all, naikkan dengan go get
replace sementara tertinggalhasil lokal ≠ hasil CIHapus replace sebelum rilis
Toolchain lebih tuago.mod requires go >= 1.xSet GOTOOLCHAIN=auto atau perbarui Go
Vendor tidak sinkroninconsistent vendoringgo mod vendor ulang
Mode GOPATH lamaperilaku import jadulGO111MODULE=on (bawaan Go modern)
Dependency tak terpakai menumpukgo.mod penuh require usanggo mod tidy berkala

Demo Nyata: go mod tidy Membersihkan Dependency #

Demo berikut dibuat di direktori sementara. Module baru diinisialisasi, satu dependency ditambahkan lewat go get, tetapi kode belum mengimpor dependency tersebut:

bash 
go mod init example.com/lampiran-demo
go get github.com/google/[email protected]

Output yang Dihasilkan:

text 
go: creating new go.mod: module example.com/lampiran-demo
go: added github.com/google/uuid v1.6.0

Isi go.mod setelah kedua perintah di atas memuat satu baris require:

text 
module example.com/lampiran-demo

go 1.27.2

require github.com/google/uuid v1.6.0 // indirect

Penanda // indirect menyatakan modul utama belum mengimpor package tersebut. Perintah diagnosis memperkuat dugaan itu:

bash 
go mod why github.com/google/uuid

Output yang Dihasilkan:

text 
# github.com/google/uuid
(main module does not need package github.com/google/uuid)

Sekarang jalankan pembersihannya, lalu periksa go.mod kembali:

bash 
go mod tidy && cat go.mod

Output yang Dihasilkan:

text 
module example.com/lampiran-demo

go 1.27.2

Baris require github.com/google/uuid lenyap tanpa jejak: go mod tidy memindai seluruh import aktual, menjaga go.mod dan go.sum hanya memuat yang benar-benar dipakai. Perintah ini bekerja senyap ketika sukses — bukti keberhasilannya memang dibaca dari isi go.mod, bukan dari keluaran terminal.

MVS: Versi Minimal, Bukan Versi Terbaru #

Kejutan klasik pemula: dua dependency sama-sama butuh golang.org/x/text, yang satu menyatakan v0.14.0 dan yang lain v0.16.0, lalu Go memilih… v0.16.0 — bukan versi terbaru yang ada (saat demo ini dibuat, v0.43.0). Inilah Minimal Version Selection (MVS): dari semua versi yang dibutuhkan module graph, Go memilih versi terkecil yang masih memenuhi seluruh kebutuhan.

Demo berikut dibangun dari tiga module lokal — moda me-require x/text v0.14.0, modb me-require v0.16.0, dan module utama menggabungkan keduanya lewat replace:

bash 
go list -m all

Output yang Dihasilkan:

text 
example.com/aplikasi
example.com/moda v0.0.0 => ../moda
example.com/modb v0.0.0 => ../modb
golang.org/x/text v0.16.0

Baris terakhir adalah hasil MVS. Ketika modb diturunkan ke v0.9.0, terpilih menjadi v0.14.0 — kebutuhan tertinggi kini milik moda:

Kebutuhan di module graphVersi terpilih
moda: v0.14.0 sajav0.14.0 (bukan v0.43.0 terbaru)
moda: v0.14.0 + modb: v0.16.0v0.16.0
moda: v0.14.0 + modb: v0.9.0v0.14.0

Demo: Galat missing go.sum entry #

Skenario kedua: kode sudah mengimpor uuid, tetapi berkas go.sum terhapus (kesalahan merge atau .gitignore berlebihan). Program demo mengurai UUID tetap agar outputnya deterministik:

go 
package main

import (
	"fmt"

	"github.com/google/uuid"
)

func main() {
	id := uuid.MustParse("123e4567-e89b-12d3-a456-426614174000")
	fmt.Println("ID tetap:", id)
}

Hapus go.sum lalu jalankan:

bash 
rm go.sum && go run .

Output yang Dihasilkan:

text 
main.go:6:2: missing go.sum entry for module providing package github.com/google/uuid (imported by example.com/lampiran-demo); to add:
	go get example.com/lampiran-demo

Pesan galat ini jujur: checksum modul uuid tidak tercatat, dan saran perbaikannya tertera. Cara paling lazim adalah go mod tidy, yang mengunduh modul dan menulis ulang kedua checksum — hash go.mod dan hash isi modul — ke go.sum:

bash 
go mod tidy && go run .

Output yang Dihasilkan:

text 
ID tetap: 123e4567-e89b-12d3-a456-426614174000

Perintah Diagnosis untuk Harian #

Empat perintah berikut menutupi hampir seluruh sesi troubleshooting module:

PerintahJawaban yang diberikan
go mod tidyApa require minimum yang benar-benar dibutuhkan?
go mod why <path>Siapa yang mengimpor package ini?
go mod verifyApakah cache modul lokal masih cocok dengan checksum?
go list -m allVersi apa yang terpilih untuk tiap modul (MVS)?

Rumus praktisnya: mulai dari go list -m all untuk melihat peta, go mod why untuk menelusuri pemakai, dan go mod tidy sebagai penutup yang merapikan. Kebingungan module yang tersisa biasanya selesai dengan tiga perintah ini.

Module yang sehat membuat proyek berjalan mulus, tetapi kualitas kode di dalamnya tetap butuh pemeriksaan manusia. Daftar periksa untuk pemeriksaan itu kita susun di chapter Checklist Code Review .

Referensi #