Help & Support

Troubleshooting

Panduan lengkap untuk mengatasi masalah umum saat menggunakan NxGate. Setiap kasus dilengkapi dengan penyebab, solusi, dan checklist debugging.

Navigasi Cepat

Kasus 1

Build Failed / 401 Unauthorized

Maven atau Gradle gagal download dependency dengan error 401 Unauthorized atau "Could not resolve dependencies".

Kemungkinan Penyebab

Token GitHub belum dikonfigurasi
Token GitHub sudah expired atau revoked
Token tidak memiliki scope read:packages
Username atau token salah ketik
Server ID di settings.xml tidak match dengan repository ID di pom.xml

Solusi

Untuk Maven - Cek settings.xml:

<!-- File: ~/.m2/settings.xml -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
    <servers>
        <server>
            <id>github</id>
            <username>YOUR_GITHUB_USERNAME</username>
            <!-- Token harus memiliki scope: read:packages -->
            <password>ghp_xxxxxxxxxxxxxxxxxxxx</password>
        </server>
    </servers>
</settings>

Untuk Gradle - Cek gradle.properties:

# File: ~/.gradle/gradle.properties
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=ghp_xxxxxxxxxxxxxxxxxxxx

# Atau gunakan environment variables:
# GITHUB_USERNAME=your_username
# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Checklist Debugging

1
Pastikan ID server di settings.xml sama dengan ID di pom.xml repository (github)
2
Generate token baru di GitHub Settings > Developer settings > Personal access tokens
3
Centang scope read:packages saat generate token
4
Jangan ada spasi atau karakter aneh di username/token

Kasus 2

ClassNotFoundException / NoClassDefFoundError

Plugin berhasil di-build tapi error saat di-load di server Minecraft dengan pesan "ClassNotFoundException: xyz.noxlydev.nxgate.NxGateClient".

Kemungkinan Penyebab

Library NxGate tidak ter-shade ke dalam JAR plugin
Dependency scope salah (provided instead of compile)
Shade plugin tidak dikonfigurasi atau tidak berjalan saat build
JAR yang di-deploy bukan JAR hasil shade (biasanya file tanpa "-shaded" suffix)

Solusi

Maven - Konfigurasi Shade Plugin:

<!-- pom.xml - Maven Shade Plugin dengan Relocation -->
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.5.0</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <relocations>
                            <!-- Relokasi package NxGate ke namespace plugin Anda -->
                            <relocation>
                                <pattern>xyz.noxlydev.nxgate</pattern>
                                <shadedPattern>com.yourplugin.libs.nxgate</shadedPattern>
                            </relocation>
                        </relocations>
                        <minimizeJar>true</minimizeJar>
                        <createDependencyReducedPom>false</createDependencyReducedPom>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Gradle - Konfigurasi Shadow Plugin:

// build.gradle - Shadow Plugin untuk Gradle
plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '8.1.1'
}

shadowJar {
    relocate 'xyz.noxlydev.nxgate', 'com.yourplugin.libs.nxgate'
    archiveClassifier.set('')
    minimize()
}

// Build dengan: gradle shadowJar

Checklist Debugging

1
Pastikan scope dependency bukan "provided" - harus "compile" atau kosong
2
Run "mvn clean package" untuk rebuild dengan shade
3
Untuk Gradle, run "gradle shadowJar" bukan "gradle jar"
4
Cek ukuran JAR - JAR yang benar biasanya lebih besar karena include dependency
5
Unzip JAR dan pastikan folder xyz/noxlydev/nxgate ada di dalamnya

Kasus 3

Lisensi Selalu Invalid

Method verify() selalu return false meskipun license key sudah benar.

Kemungkinan Penyebab

License key salah atau typo
License sudah expired
Server HWID (Hardware ID) tidak cocok dengan yang terdaftar
Koneksi ke API NxGate timeout atau terblokir firewall
Server dalam mode offline dan tidak bisa menghubungi API

Solusi

Debug Code untuk Investigasi:

// Debug kode untuk troubleshoot license issues
public void onEnable() {
    saveDefaultConfig();
    
    String licenseKey = getConfig().getString("license.key");
    getLogger().info("[DEBUG] License key loaded: " + 
        (licenseKey != null ? licenseKey.substring(0, 4) + "****" : "NULL"));
    
    NxGateClient client = new NxGateClient(licenseKey);
    
    // Log server info untuk debugging
    getLogger().info("[DEBUG] Server IP: " + getServer().getIp());
    getLogger().info("[DEBUG] Server Port: " + getServer().getPort());
    getLogger().info("[DEBUG] Online Mode: " + getServer().getOnlineMode());
    
    boolean isValid = client.verify();
    
    // Log hasil verifikasi detail
    getLogger().info("[DEBUG] Verification result: " + isValid);
    getLogger().info("[DEBUG] Response message: " + client.getMessage());
    
    if (!isValid) {
        getLogger().severe("===========================================");
        getLogger().severe("LICENSE VERIFICATION FAILED");
        getLogger().severe("Error: " + client.getMessage());
        getLogger().severe("===========================================");
        getServer().getPluginManager().disablePlugin(this);
    }
}

Implementasi Retry Logic:

// Implementasi retry logic dengan exponential backoff
public boolean verifyWithRetry(NxGateClient client, int maxRetries) {
    int retryDelay = 2000; // Start with 2 seconds
    
    for (int attempt = 1; attempt <= maxRetries; attempt++) {
        getLogger().info("[NxGate] Verification attempt " + attempt + "/" + maxRetries);
        
        try {
            if (client.verify()) {
                return true;
            }
            
            String error = client.getMessage();
            getLogger().warning("[NxGate] Attempt " + attempt + " failed: " + error);
            
            // Jangan retry jika error bukan connection issue
            if (error.contains("INVALID_KEY") || error.contains("EXPIRED")) {
                getLogger().severe("[NxGate] License error (no retry): " + error);
                return false;
            }
            
        } catch (Exception e) {
            getLogger().warning("[NxGate] Connection error: " + e.getMessage());
        }
        
        if (attempt < maxRetries) {
            try {
                Thread.sleep(retryDelay);
                retryDelay *= 2; // Exponential backoff
            } catch (InterruptedException ignored) {}
        }
    }
    
    return false;
}

Checklist Debugging

1
Double-check license key di config.yml (copy-paste dari dashboard)
2
Cek console log untuk pesan error spesifik dari getMessage()
3
Pastikan server bisa akses internet (test dengan curl/ping)
4
Cek apakah firewall memblokir koneksi outbound ke API
5
Hubungi support jika error "HWID_MISMATCH" untuk reset HWID

Kasus 4

Konflik Versi dengan Plugin Lain

Error "LinkageError", "NoSuchMethodError", atau behavior aneh ketika ada plugin lain yang juga menggunakan NxGate.

Kemungkinan Penyebab

Dua plugin menggunakan versi NxGate yang berbeda
Salah satu atau kedua plugin tidak melakukan relocation saat shading
Class dari plugin A di-load oleh classloader plugin B
Shared classloader conflict di beberapa server implementation

Solusi

Relocation dengan Unique Namespace:

<!-- Relokasi dengan unique namespace per plugin -->
<relocation>
    <pattern>xyz.noxlydev.nxgate</pattern>
    <!-- Gunakan package name yang UNIK untuk setiap plugin -->
    <shadedPattern>com.yourname.pluginname.internal.nxgate</shadedPattern>
</relocation>

<!-- Contoh untuk plugin berbeda: -->
<!-- Plugin A: com.yourname.plugina.internal.nxgate -->
<!-- Plugin B: com.yourname.pluginb.internal.nxgate -->

Checklist Debugging

1
Pastikan SETIAP plugin yang menggunakan NxGate melakukan relocation
2
Gunakan namespace yang UNIK per plugin (include nama plugin dalam shadedPattern)
3
Rebuild SEMUA plugin yang terlibat dengan relocation baru
4
Hapus file .class yang ter-cache di server (folder plugin/.cache jika ada)
5
Restart server sepenuhnya (bukan reload) setelah update plugin

Masih Butuh Bantuan?

Jika masalah Anda belum terselesaikan setelah mencoba semua solusi di atas, jangan ragu untuk menghubungi kami melalui GitHub Issues atau Discord community.

Buka GitHub Issue Join Discord