Skip to content
Handoff Wizard

Troubleshooting

This page covers the ten most likely issues. If yours isn’t listed, email support@handoffwiz.com with your project code (the one you entered during onboarding) and a one-line description.

1. Project code rejected {#project-code-rejected}

Symptom: During onboarding step 1.3, the licensing API returns “Project code not found” or “Project code expired”.

Cause + fix:

  • Typo. The code is HND- followed by three groups of four characters. Re-check the email your employer sent. The dashes are required.
  • Sign-in mismatch. Some project codes are scoped to a specific email address. Re-check that the SSO email you signed in with matches the email your employer enrolled.
  • Expired code. Project codes expire 60 days after issue. Ask your employer’s admin to regenerate from the admin dashboard at app.handoffwiz.com.

If the code still won’t validate, email support@handoffwiz.com with the code and your employer’s company name.

2. Anthropic API key invalid {#anthropic-key-invalid}

Symptom: During onboarding step 1.5, the wizard reports “Key validation failed”.

Cause + fix:

  • Wrong key format. Valid Anthropic keys start with sk-ant-. If yours doesn’t, you copied something else (an OpenAI key, a session token, a workspace ID).
  • Key has zero credit. Free Anthropic accounts get $5 of trial credit; once exhausted, key auth still works but inference 402s. Add credit at console.anthropic.com/billing.
  • Key revoked. If you regenerated the key in the Anthropic console after copying, the old one is dead. Copy the new one.
  • Region restriction. Some Anthropic accounts are workspace-scoped — verify the key is workspace-default (or matches the workspace you intend to bill).

3. GCP service account JSON malformed {#gcp-json-malformed}

Symptom: During onboarding step 1.6, the wizard reports “JSON parse failed” or “Missing required field: client_email”.

Cause + fix:

A valid GCP service account JSON has all of: type: "service_account", project_id, private_key_id, private_key, client_email, client_id, auth_uri, token_uri, auth_provider_x509_cert_url, client_x509_cert_url. If any are missing, the file is partial.

  • Re-download from GCP. Go to IAM & Admin → Service Accounts, find the account your employer told you to use, click Keys → Add Key → Create new key → JSON, and use the freshly downloaded file.
  • Don’t open + re-save in a text editor. Some editors strip newlines from the private_key field, which silently corrupts the key. Drag the original downloaded file directly onto the wizard.

4. GCP permission denied {#gcp-permission}

Symptom: GCP credentials parse fine, but the wizard reports “Service account lacks aiplatform.notebooks.create permission” or “Cannot list NotebookLM notebooks in project”.

Cause + fix: The service account needs the NotebookLM Enterprise User IAM role (or the broader Vertex AI User role) on the GCP project.

Forward this to your employer’s IT person:

Please grant the service account <service-account-email> the roles/aiplatform.user role on the GCP project that hosts NotebookLM Enterprise. The wizard needs this to create the post-handover notebook.

The service account email is shown on the GCP credentials screen and is also visible in the JSON file’s client_email field.

5. File too large to ingest {#file-too-large}

Symptom: A file appears in the file-intake screen with a red “Too large” badge and a Skipped status.

Cause: Per-file limit is 100 MB. Most operational files are well under this; large ones are usually multi-GB exports of an entire Slack workspace or a deep video archive.

Fix:

  • Split the file (e.g. an 800 MB Slack export) into per-channel JSON dumps under 100 MB each, then re-drop the folder.
  • Skip if the file is video, audio, or a binary — those formats provide no textual signal anyway.
  • Replace a large PDF with the smaller original (often the giant PDF is a scanned doc; the source .docx is 3 MB).

If you genuinely need to ingest a >100 MB textual corpus, email support@handoffwiz.com — we’ll bump your limit case-by-case.

6. Resume an interrupted interview {#resume-interview}

Symptom: You closed the laptop or quit mid-interview and want to pick up where you left off.

Fix: Re-launch Handoff Wizard. The app autosaves on every keystroke and on every chat turn. On launch the dashboard shows the Interviews track at the same percentage as before, and clicking the in-progress session re-opens at the exact question. No data loss has been reported in any session that exceeded 30 seconds of typing.

If the app crashed and lost progress (unlikely but possible), see App crashed mid-session.

7. NotebookLM upload failed {#notebooklm-upload-fail}

Symptom: Step 7 (publish) returns “NotebookLM API error” with a 4xx or 5xx code.

Cause + fix:

  • 403 Forbidden. Service account is missing the aiplatform.notebooks.create permission. See #4 GCP permission denied.
  • 404 Not Found. The GCP project doesn’t have NotebookLM Enterprise enabled. Your employer must enable the Vertex AI API (and confirm NotebookLM Enterprise is provisioned, ~$9/user/mo) in the GCP console.
  • 429 Too Many Requests. GCP throttling. Click Retry — the wizard backs off and retries automatically up to 3 times.
  • 500 Internal Server Error from GCP. Transient. Click Retry. If it persists for >30 minutes, email support@handoffwiz.com.

The 16 approved docs are saved locally — even if upload fails repeatedly, you don’t lose your work.

8. Synthesis generated wrong content {#synthesis-wrong}

Symptom: A draft document contains a section that’s incorrect, missing context, or hallucinated.

Fix: Click Reject + Regenerate on that doc. In the reason field, be specific:

  • “The ‘Vendor map’ section listed Acme Corp as our payment processor — that’s wrong, Stripe is. Source: my interview session 2 answer about billing.”
  • “The ‘Open loops’ doc invented a project called ‘Phoenix’ that doesn’t exist. Drop it.”

Regeneration takes ~1-2 minutes per doc and uses about $0.40 of Anthropic credit. The new draft replaces the old one. Most rejected docs pass on regen; if a doc fails twice, the underlying interview answer probably needs more detail — open the relevant interview session and add it.

9. Validation failed (under 30/35) {#validation-low-score}

Symptom: Step 6 gold validation lands below 30/35 and the publish button is disabled.

Fix: The validation results screen shows each failing question with:

  • Which interview session was supposed to source the answer.
  • The grounded-answer search the wizard ran against your drafts.
  • A short note on what context was missing.

Click Add detail on each failing question. The wizard re-opens the source interview session with a focused 3-5 minute follow-up. After answering, re-run validation. Most users land 32-34/35 after one round of follow-ups.

If you’re still stuck below 30/35 after two rounds, email support@handoffwiz.com — the issue is usually that the gold question bank doesn’t match your specific operating context, and we’ll work with you to authorize an alternate question.

10. App crashed mid-session {#app-crash}

Symptom: The wizard hard-closed during use. On re-launch, you see an autosave-restored banner.

Fix: Click Resume from autosave. The app restores to the last keystroke-level checkpoint, which is at most a few seconds of work behind the crash.

If the crash is reproducible (it happens every time you click X):

  1. Open Settings → Diagnostics.
  2. Click Send anonymized crash report. The report includes a stack trace + redacted state — no source content.
  3. Email support@handoffwiz.com with the crash ID printed in the dialog.

How do I redo a session? {#redo-session}

Symptom: You approved an interview session and now want to redo it from scratch.

Fix: Open Settings → Reset session. Pick the session you want to redo. The wizard archives the prior session transcript (it stays on disk for audit) and re-opens that session at question 1. The Interviews track percentage drops accordingly. Re-running synthesis after a session reset costs another ~$0.40 × 16 docs in Anthropic credit.

Resetting a session after publishing to NotebookLM does not unpublish — your employer would need to delete the published notebook from their GCP console if they want a re-do.

Still stuck? Email support@handoffwiz.com with your project code and we’ll respond within one business day during the engagement period.