Troubleshooting

Development Issues

1. protoc not found saat compile

Gejala:

error: failed to run custom build command for `prost-build`
Could not find `protoc` installation

Solusi:

# macOS
brew install protobuf

# Ubuntu/Debian
apt-get install -y protobuf-compiler

# Verifikasi
protoc --version

Proto compiler dibutuhkan karena semua backend services compile .proto files saat cargo build.

2. SQLx compile-time check gagal

Gejala:

error: error communicating with database: connection refused

SQLx melakukan compile-time query validation terhadap database yang hidup.

Solusi:

# Pastikan PostgreSQL running
pg_isready

# Set DATABASE_URL
export DATABASE_URL=postgresql://localhost/waqfuel_auth

# Atau gunakan offline mode (dari cached query metadata)
cargo sqlx prepare

3. gRPC connection refused antar services

Gejala:

transport error: error trying to connect: tcp connect error: Connection refused

Solusi:

• Pastikan service target sudah running di port yang benar
• Development: gunakan localhost:<port>
• Production (Fly.io): gunakan <app-name>.internal:<port>
• Cek apakah port gRPC di-bind ke 0.0.0.0 (bukan 127.0.0.1)

4. JWT verification failed di main-api

Gejala:

401 Unauthorized - Invalid token signature

Solusi:

• Pastikan JWKS endpoint accessible: curl http://localhost:3001/.well-known/jwks.json
• Pastikan JWT_KEY_ID di auth-api sama dengan yang di JWKS response
• Token expired? Access token hanya berlaku 900 detik (15 menit)
• Refresh token: POST /auth/refresh dengan cookie refresh_token

5. S3 Access Denied saat upload

Gejala:

AccessDenied: User: arn:aws:iam::... is not authorized to perform: s3:PutObject

Solusi:

Pastikan IAM policy mencakup semua actions yang dibutuhkan:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:PutObject",
      "s3:GetObject",
      "s3:DeleteObject",
      "s3:ListBucket"
    ],
    "Resource": [
      "arn:aws:s3:::waqfuel-assets",
      "arn:aws:s3:::waqfuel-assets/*"
    ]
  }]
}

6. Resend email gagal terkirim

Gejala:

Auth API log menunjukkan error saat gRPC call ke notif-api.

Solusi:

• Cek RESEND_API_KEY valid di notif-api
• Cek domain waqfuel.com sudah verified di Resend dashboard
• Cek rate limit Resend (100 emails/day di free tier)
• Development: gunakan sandbox mode Resend

7. Reference API migration sangat lama

Gejala:

Migration 20250801010702_create_locations_table.sql memakan waktu lama (~2.8MB data lokasi Indonesia).

Solusi:

Ini normal — migration ini meng-insert seluruh data lokasi Indonesia (provinsi, kota, kecamatan, kelurahan). Biarkan selesai (~1-5 menit tergantung koneksi database).

Production Issues

8. Fly.io machine auto-stopped

Gejala:

Service tidak merespons setelah idle beberapa saat.

Penjelasan:

auto_stop_machines = "stop" di fly.toml akan menghentikan machine saat idle. Machine auto-start saat ada request masuk, tapi cold start memakan ~2-5 detik.

Solusi:

Untuk service yang harus always-on (misal auth-api karena gRPC):

min_machines_running = 1

9. Database connection pool exhausted

Gejala:

too many connections for role

Solusi:

• Neon free tier: max 5 concurrent connections
• Tambahkan connection pooler (Neon PgBouncer): gunakan pooler URL di DATABASE_URL
• SQLx pool config: set max_connections sesuai tier

10. CORS error di frontend

Gejala:

Access to fetch at 'https://auth.waqfuel.com/...' from origin 'https://waqfuel.com' has been blocked by CORS policy

Solusi:

Pastikan CORS_ALLOWED_ORIGINS di env vars backend mencakup domain frontend:

CORS_ALLOWED_ORIGINS=https://waqfuel.com,https://platform.waqfuel.com,http://localhost:3000