Masalah Umum & Solusinya

Kumpulan masalah yang benar-benar pernah terjadi saat membangun dan menjalankan Kantor AI, beserta penyebab dan solusinya. Banyak di antaranya sudah ditangani otomatis oleh sistem. Bab ini menjelaskan apa yang terjadi di baliknya.

Cara membaca: Gejala, lalu Penyebab dan Solusi. Tanda ✅ = sudah ditangani otomatis oleh sistem.

A. Claude & agen AI

A1. Aplikasi pihak ketiga menolak token langganan Claude (HTTP 401)

• Penyebab: token langganan Claude Pro/Max tidak bisa dipakai di aplikasi agen pihak ketiga. Kantor AI awalnya dirancang dengan Hermes Agent dan gagal karena ini.
• Solusi: jalankan agen lewat Claude Code resmi (claude -p) yang login dengan akun Anda. Ini dasar seluruh arsitektur.

A2. "You've hit your session limit · resets 5:20am"

• Penyebab: kuota jendela 5 jam langganan Claude habis. Satu produksi penuh memakai porsi yang besar.
• Solusi ✅: sistem mendeteksi pesan limit, menunggu sampai jam reset (+5 menit), memberi tahu Anda sekali, lalu mengulang langkah yang sama saja, tidak dari awal. Produksi harian channel utama punya batas akhir 15.30: kalau lewat, agen manajer melapor dan video digeser ke jadwal berikutnya.
• Pencegahan: beri jarak jam produksi antar-channel; pakai model hemat (Haiku/Sonnet) untuk agen yang tugasnya ringan (panel → Tim & AI); hindari memakai Claude untuk keperluan pribadi berat di jam produksi.
• Batas mingguan (reset > 6 jam lagi) tidak ditunggu otomatis. Produksi dilaporkan gagal, lalu dilanjutkan setelah kuota pulih.

A3. Agen menulis file di luar foldernya / menjalankan perintah

• Penyebab: izin tool terlalu longgar.
• Solusi ✅: agen hanya diizinkan Read, Glob, Grep, WebSearch, WebFetch, Skill dan menulis hanya di catatan/**; Bash dilarang. Agen manajer hanya boleh menjalankan CLI kantor yang daftar perintahnya tetap. Jangan pernah memberi agen shell bebas, karena bisa disalahgunakan lewat prompt injection (misalnya dari isi halaman web yang ia baca).

A4. Hasil agen tidak sesuai format (storyboard tidak valid)

• Solusi ✅: pipeline memvalidasi hasil (mis. nomor kalimat per adegan harus berurutan) dan meminta agen menulis ulang, maksimal 2 kali. Kalau tetap gagal, produksi berhenti dengan pesan jelas dan bisa dilanjutkan.

B. Suara

B1. Edge TTS tiba-tiba gagal (HTTP 403)

• Penyebab: Microsoft mengubah protokol, sehingga versi lama paket edge-tts ditolak.
• Solusi ✅: sistem otomatis memperbarui edge-tts (pip install --upgrade edge-tts) saat mendapat 403, lalu mencoba lagi.

B2. Suara Gemini terdengar, tapi subtitle tidak sinkron / "timestamp kata hanya 88% cocok"

• Penyebab: Gemini TTS tidak memberi waktu per kata. Waktunya didapat dengan menyimak ulang audio memakai Whisper, lalu dicocokkan ke naskah. Nama asing atau angka kadang salah dengar.
• Solusi ✅: beberapa cara pencocokan dicoba sampai ≥ 90% kata cocok. Kalau tetap kurang, sistem pindah ke ElevenLabs (penutur asli bahasanya), lalu Edge TTS.
• Efek samping: suara video itu berbeda dari suara biasa channel. Tambahkan kata yang sering salah ke kamus pelafalan agen suara.

B3. Arahan gaya ikut dibacakan ("Bacakan dengan hangat…" terdengar di narasi)

• Penyebab: Gemini TTS menerima arahan gaya dan naskah dalam satu teks, dan kadang ikut membacakan arahannya.
• Solusi ✅:
  • Arahan ditulis sebagai satu kalimat perintah yang diakhiri titik dua (pola dokumentasi Gemini, mis. "Bacakan dengan hangat:").
  • Hasil audio disimak ulang dengan Whisper dan dicocokkan dengan naskah. Kata ekstra sebelum awal atau sesudah akhir naskah dipotong dari audio, lalu timestamp dihitung ulang.

B5. Subtitle menyambung melewati batas kalimat ("popcorn Lalu ia")

• Penyebab: data waktu per kata dari Edge TTS tidak menyertakan tanda baca, sehingga pemotong subtitle yang mencari titik/koma tidak pernah terpicu.
• Solusi ✅ (versi mini): potong subtitle di jeda bicara. Hasil ukur: akhir kalimat ±780 ms, koma ±300 ms, antar-kata ±0 ms, jadi ambang 200 ms memisahkan kalimat dengan rapi.

B4. Durasi narasi di luar target (mis. 67 detik untuk target 40–55)

• Penyebab: naskah terlalu panjang atau suara cadangan lebih lambat.
• Solusi: dicatat sebagai temuan audio (tidak memblokir). Bila sering terjadi, tambahkan aturan jumlah kata di pedoman agen penulis naskah lewat panel.

C. Video & render

C1. Chrome gagal jalan saat render di Ubuntu 24.04 ("No usable sandbox")

• Penyebab: Ubuntu 24.04 memblokir sandbox Chrome (AppArmor user namespace).
• Solusi ✅: Chrome headless dijalankan lewat pembungkus dengan --no-sandbox (sama seperti yang dilakukan Remotion).

C2. Server kehabisan memori saat render

• Penyebab: Chromium + Whisper + Claude berjalan bersamaan di VPS 4 GB.
• Solusi ✅: render selalu satu per satu (kunci produksi), --concurrency 2, swap 4 GB.

C3. Kode animasi buatan AI tidak bisa dirender / berbahaya

• Solusi ✅: sebelum dijalankan, kode buatan agen animator diperiksa:
  • Mesin kartun: hanya boleh mengimpor pustaka yang disediakan, lalu dicek dengan tsc dan dirender cuplikan gambarnya.
  • Mesin studio: pola terlarang ditolak, misalnya child_process, fs, akses jaringan, dan eval.
  • Galat dikembalikan ke agen animator untuk diperbaiki, maksimal 2 putaran.

C4. Episode kartun lama "hilang" setelah deploy

• Penyebab: remotion/src/cartoon/episodes/index.ts dibuat otomatis di server. Deploy pertama hampir menimpanya dengan versi repo.
• Solusi ✅: folder episodes/ dikecualikan dari deploy. Aturan umumnya: file yang dibuat sistem di server tidak boleh ditimpa dari repo.

D. YouTube

D1. Video hasil unggahan API terkunci "private"

• Penyebab: proyek Google Cloud yang belum diaudit bisa membuat unggahan API terkunci private.
• Solusi: periksa dengan mengubah satu video ke Public di YouTube Studio. Bila berhasil, channel Anda tidak terkunci, dan sistem menjadwalkan tayang dengan publishAt. Bila terkunci, set audit_lolos: false di ~/.kantor-youtube/config.json dan ajukan audit API ke Google.

D2. Izin channel kedaluwarsa setiap 7 hari ("invalid_grant")

• Penyebab: layar persetujuan OAuth Google masih berstatus Testing.
• Solusi: di Google Cloud → OAuth consent screen → Audience, tekan Publish app (In production).

D3. "redirect_uri_mismatch" saat menghubungkan channel

• Solusi: tambahkan alamat callback persis seperti yang ditampilkan panel (Konektor → Google OAuth client) ke Authorized redirect URIs, lalu unduh ulang file JSON-nya.

D4. Unggahan gagal "quotaExceeded"

• Penyebab: kuota YouTube Data API 10.000 unit/hari per proyek. Satu unggahan ±1.600 unit, jadi maksimal ±6 video per hari per proyek.
• Solusi ✅: sistem menghitung pemakaian. Bila tidak cukup, unggahan ditunda otomatis dan dilanjutkan setelah kuota reset (±14.00 WIB). Sinkron status dibuat hemat (tiap 2 jam).
• Lebih dari 6 channel: pakai proyek Google Cloud kedua.

D5. Foto/banner channel tidak tampil di panel

• Penyebab: server gambar Google menolak permintaan yang membawa header Referer.
• Solusi ✅: gambar dimuat dengan referrerPolicy="no-referrer".

E. Instagram

E1. Tombol "Hubungkan akun Instagram" tidak bisa dipakai di PC

• Penyebab: Meta mengambil video dari alamat publik (https). PC rumahan umumnya tidak punya alamat publik.
• Solusi: untuk sekarang Instagram hanya di mode server (VPS + domain).

E2. "Izin belum lengkap" atau akun bukan Professional

• Solusi: ubah akun menjadi Professional (Creator/Business) di aplikasi Instagram, ulangi Hubungkan, lalu centang semua izin. Bila aplikasi Meta masih mode pengembangan, tambahkan akun sebagai Instagram Tester lalu terima undangannya di Instagram.

E3. Instagram menolak video (status ERROR)

• Solusi ✅: percobaan kedua otomatis 10 menit kemudian dengan audio di-encode ulang (AAC 128 kbps/48 kHz, faststart). Bila tetap gagal: laporan di Discord + tombol "Kirim ulang ke IG" di panel.

F. Jadwal & rencana

F1. Rencana topik tidak muncul di kalender / slot memilih topik sendiri

• Penyebab: tim menulis kolom tanggal dalam format berbeda-beda: 30/10, 2026-10-30, Selasa, 27/10.
• Solusi ✅: satu pembaca tanggal bersama (jadwal.py) mengenali semua format itu, termasuk pergantian tahun (rencana akhir Desember yang berisi 02/01).

F2. Topik dobel setelah video uji coba

• Penyebab: rencana disusun tanpa tahu topik video uji yang sudah tayang.
• Solusi: ganti topik tanggal itu lewat kalender di panel (perubahan Anda selalu menang atas rencana tim).

F3. Channel baru belum punya rencana

• Perilaku: agen penulis naskah memilih topik sendiri sesuai niche, sambil menghindari judul yang pernah dibuat. Rencana dibuat pada penyusunan Kamis berikutnya, atau langsung dengan kantor rencana <channel> <mulai> <sampai>.

G. Server, Windows & deploy

G1. File skrip rusak di Linux setelah dikirim dari Windows (\r: command not found)

• Penyebab: akhir baris CRLF (Windows).
• Solusi ✅: .gitattributes dengan * text=auto eol=lf, sehingga semua file di repo memakai LF.

G2. Di Windows, mengecek proses justru mematikannya

• Penyebab: os.kill(pid, 0) di Windows menghentikan proses, tidak seperti di Linux yang hanya mengecek.
• Solusi ✅: semua cek proses lewat sistem.hidup(pid) (psutil/WinAPI).

G3. Produksi ikut mati saat deploy

• Penyebab: me-restart layanan yang menjadi induk proses produksi (mis. bot Discord yang memulai revisi) ikut mematikan anak prosesnya.
• Solusi ✅: deploy menunda restart layanan bila ada kunci produksi (.produksi.lock). Jalankan deploy di luar jam produksi.

G4. caddy validate gagal "permission denied" pada file log

• Solusi ✅: validasi dijalankan sebagai user caddy (sudo -u caddy caddy validate …). Caddyfile hanya dipasang bila valid, dan versi lamanya disimpan sebagai cadangan.

G6. Perintah memasang cron gagal di server baru

• Penyebab: pengguna yang belum punya crontab membuat crontab -l (dan grep) mengembalikan kode gagal. Di shell yang ketat (set -e -o pipefail), baris jadwalnya tidak pernah terpasang.
• Solusi ✅: { crontab -l 2>/dev/null | grep -v kantor-mini || true; echo '…'; } | crontab -, yang aman di server baru dan aman dijalankan berulang (tidak membuat baris dobel).

G5. Video dianggap "tayang terlalu cepat" padahal dijadwalkan

• Periksa dulu apakah video itu dipublikasikan manual di YouTube Studio. Itu bukan galat sistem.

Menemukan masalah baru? Catat di bab ini dengan pola yang sama (Gejala → Penyebab → Solusi) supaya pemakai dan AI berikutnya tidak mengulang pencarian yang sama.