Troubleshooting Guide

Common issues, error messages, and solutions for Handover implementation and operation.

troubleshootingcommon issueserror messagesdebuggingsupport

Overview

Solve common Handover implementation issues with this troubleshooting guide. Covers setup problems, authentication issues, and runtime errors.

Content Not Loading

If getContent() returns empty or errors, check these common causes.

Verify NEXT_PUBLIC_HANDOVER_API_URL is set correctly
Confirm NEXT_PUBLIC_HANDOVER_API_KEY format (ho_live_* or ho_test_*)
Check project is not locked in dashboard
Verify API key matches project in dashboard
Check browser console for CORS errors
Ensure environment variables are prefixed with NEXT_PUBLIC_

Verify username is exact match (case-sensitive)
Check password meets requirements (10+ chars, upper, lower, number)
Account may be rate-limited (wait 30 minutes after 5 failures)
Session may be expired (7-day TTL)
Check localStorage for 'handover_admin_session' token
Try clearing browser cache and cookies

// Debug session in browser console
const token = localStorage.getItem("handover_admin_session");
console.log("Session token:", token);

if (!token) {
  console.log("No session - need to login");
}

javascript

Image Upload Fails

Upload errors usually indicate file validation or quota issues.

STORAGE_LIMIT_EXCEEDED - Upgrade plan or delete unused images
INVALID_IMAGE_TYPE - Only image/* MIME types accepted
File size too large - Consider compressing image
Network timeout - Try smaller file or faster connection
Check browser console for detailed error code

try {
  await handover.uploadImage(file, token);
} catch (error) {
  console.error("Upload error:", error.code, error.message);
  if (error.code === "STORAGE_LIMIT_EXCEEDED") {
    alert("Storage limit reached. Delete unused images or upgrade.");
  }
}

typescript

Project Locked Error

HTTP 402 errors indicate the project is locked in the dashboard.

Check project lock status in dashboard
Unlock project if payment issue resolved
Lock is immediate - no cache delay
All API calls return 402 when locked
SDK throws HANDOVER_LOCKED error automatically

Build Errors

TypeScript or build errors during npm run build.

Ensure @handoverhq/sdk is installed
Check Next.js version compatibility (requires 13+)
Verify tsconfig.json includes necessary compiler options
Clear .next folder and rebuild
Check for typos in environment variable names

CORS Errors

Cross-origin errors when calling Handover API.

Verify NEXT_PUBLIC_HANDOVER_API_URL uses https://
Ensure URL does not have trailing slash
Check browser blocks third-party cookies (not required)
Confirm API endpoint has CORS enabled (should be automatic)

Getting Help

If issues persist after troubleshooting, gather this information for support.

Error message and error code
Browser console logs
Network tab showing failed request
Environment (development/production)
SDK version (check package.json)
Steps to reproduce the issue

Source doc

This page maps to docs/ISSUES.md in the repository.

Related guides

SDK Reference

Full error code documentation.

Lock state and errors

Handle error states in UI.

Back to docs