BranchPy
Log in

Docs-Builder

# Troubleshooting

Version: 1.1.1
Last Updated: January 23, 2026

License Required Panel Appears

Causes:

  • Not logged in (no auth.json)
  • License token expired or offline days exceeded
  • Feature not in plan (entitlement missing)

Fix:

  1. branchpy license login (or device flow in VS Code)
  2. branchpy license status --json to confirm plan/features
  3. If Ren’Py user, run branchpy license claim-renpy (idempotent)

Device Approval Not Completing

Symptoms: /device/start succeeds, but no /device/poll, device not visible on website.

Checks:

  • Extension: ensure pollDeviceAuthorization is invoked (add logs if needed).
  • Rebuild extension: npm run compile to align compiled JS with TypeScript.
  • Verify secret storage writes only after poll success (no early sync).
  • Inspect logs for pollDeviceAuthorization entries; if absent, debug message routing.

Workaround: Use email/password login flow to bypass device approval until fixed.

Token Refresh Fails (401/403)

Causes:

  • Refresh token revoked/expired
  • auth_sessions entry missing
  • Case-insensitive email mismatch pre-migration

Fix:

  1. Re-login to issue new refresh/license tokens
  2. Verify Migration 024 applied (email unique, lowercased)
  3. Confirm request uses Authorization: Bearer <access_token>

Duplicate Email Constraint Errors

Symptom: duplicate key value violates unique constraint "idx_website_users_email_lower"

Context: Migration 024 enforces case-insensitive email uniqueness.

Resolution:

  1. Identify duplicates:
SELECT LOWER(email), COUNT(*) FROM website_users GROUP BY LOWER(email) HAVING COUNT(*) > 1;
  1. Merge or remove duplicates, then retry insert/migration.

Profile Button Does Nothing

Cause: Missing auth.openProfile handler in Control Center webview. Fix: Implement handler to call vscode.env.openExternal(profileUrl) using entitlements/profile URL.

CLI/Extension Shows Unregistered After Claim

Causes:

  • entitlements fetch was using missing getEntitlements() method (fixed)
  • auth.json written before poll completion
  • Governance events show login success but no entitlements fetch

Fix:

  • Ensure extension includes getEntitlements() (build 2026-01-21-HANDOFF-FIX-A or later)
  • Re-run device flow after rebuild; confirm /license/me returns plan renpy_free.

Database Verification Connectivity Errors

Symptom: ENOTFOUND postgres.railway.internal when verifying migration. Fix: Use CORE_DB_URL_PROXY (Railway proxy) and allow self-signed cert for verification scripts: NODE_TLS_REJECT_UNAUTHORIZED=0.

References

  • auth-licensing-sso/AUTHENTICATION_FIXES_2026-01-22.md
  • auth-system-closure/TROUBLESHOOTING.md
  • auth-system-closure/QA.md