Troubleshooting

If you get stuck during setup, check here first. The fixes for every recurring error pattern are listed below.

API issues

”Enable” button is greyed out

Cause: The selected project is owned by a Workspace organization, and your account doesn’t have permission to enable APIs on it.

Fix:

• From the avatar menu at the top-right, switch to a personal Google account
• Redo Step 1 with that account

---

”This API is disabled” error

Cause: One of the APIs that the requested scope depends on hasn’t been enabled in your project.

Fix:

• Open Step 2 again
• Confirm all three (Gmail API / Calendar API / Drive API) appear under “Enabled APIs & services”

---

OAuth client issues

”Access blocked: Authorization Error”

Three usual culprits:

1. You picked Web application in Step 4

   • Delete the old client from Credentials
   • Recreate via Step 4 with Desktop app
   • Paste the new Client ID / Client Secret in Step 5

2. You didn’t add your Google account as a test user

   • Go to Step 3 → Audience → Test users, add your email

3. OAuth consent screen wasn’t fully saved

   • Make sure every step of the Google Auth Platform wizard was advanced through “Next” / “Continue” / “Create"

---

"Google hasn’t verified this app” warning

This is normal. Testing-mode OAuth apps always show this warning, even though you built them yourself.

To pass: The warning page’s bottom-right has “Continue” (text link) and “Back to safety” (blue button). Click the understated text-link Continue to proceed.

Hitting “Back to safety” aborts the OAuth flow. If you misclick, just press Connect in the dashboard again.

Submitting for Google verification (Publishing) removes the warning, but personal use doesn’t need that — Testing-mode is fine.

---

Lost the Client Secret

Once the creation dialog closes, the same string never comes back. Reset it:

1. Cloud Console → Credentials
2. Click the OAuth client name
3. Click ADD SECRET or Reset secret
4. Copy the new value → re-paste in Step 5

The old secret is immediately invalidated.

---

Dashboard issues

”Could not load integrations”

Cause: The dashboard can’t reach the launcher / picoclaw process.

Fix:

1. Confirm the launcher / picoclaw process is running in your terminal
2. Open http://localhost:8080/api/integrations/list directly — JSON should come back
3. If not, restart the process

---

Saved Client ID / Secret but still shows “BYO credentials missing”

Causes and fixes:

• Whitespace in the pasted value → Open Update credentials, re-enter cleanly
• You didn’t click Save → Re-click
• Process is holding stale config → Restart Kura-chan and reload the dashboard

---

”Connect” doesn’t open a new tab

Cause: Browser pop-up blocker or an ad blocker extension.

Fix:

• Allow pop-ups from localhost
• Temporarily disable ad blockers
• In the URL bar, the browser shows a pop-up-blocked indicator — click “Allow”

---

Stuck on “Waiting for consent…”

Cause: The OAuth tab was closed or you hit “Cancel” inside it.

Fix:

• Click Connect again — a new session starts
• Don’t close the new tab; sign in and click Continue until done

---

”Insufficient Permission” after seemingly connecting

Cause: The scopes you asked for and the scopes you granted are out of sync.

Fix:

• In the Tools section, toggle the affected tool back to Read-only
• Click Connect again — Google now asks for the additional scope, click Continue

---

Full reset

If you want to start completely fresh:

1. In Kura-chan: Click Disconnect on every connection row
2. Clear credentials: Click Update credentials, save with blank values (or remove the file under ~/.config/kuraclaw/)
3. Revoke at Google: myaccount.google.com/permissions → your OAuth client → Remove Access
4. Delete the OAuth client: Google Cloud Console → Credentials → delete the client
5. Delete the project (optional): Cloud Console → IAM & Admin → Settings → Shut Down (30-day grace period)

Then redo from Step 1.

---

Still not working?

• Walk through Verify the connection check-by-check
• Note the exact error text in the dashboard (small red text under the button)
• Check the launcher / picoclaw logs, usually under ~/.config/kuraclaw/logs/