Troubleshooting

This guide covers common issues you might encounter when using HubSpot Form Builder and how to resolve them.

Connection Issues

Error: “localhost refused to connect”

This error occurs when one or both servers (frontend or backend) are not running.

Solution: Ensure both servers are running in separate terminal windows:

# Terminal 1 - Backend
cd main/server
npm run dev
# Should see: "Server running on http://0.0.0.0:3001"

# Terminal 2 - Frontend  
cd main/frontend
npm run dev
# Should see: "Local: http://localhost:5173"

Verification:

Backend should be accessible at http://localhost:3001
Frontend should be accessible at http://localhost:5173
Check terminal output for any error messages

Error: “Not allowed by CORS”

This error indicates a mismatch between the frontend URL and the CORS configuration in the backend.

Solution: Verify that FRONTEND_URL in your backend .env file matches your actual frontend URL: For local development:

# main/server/.env
FRONTEND_URL=http://localhost:5173/

For Cloudflare tunnels:

# main/server/.env  
FRONTEND_URL=https://your-frontend-tunnel.trycloudflare.com/

Make sure to include the trailing slash in FRONTEND_URL.

Additional steps:

Restart the backend server after changing .env
Clear your browser cache
Try accessing from an incognito window

CORS Error: “Loopback address space blocked”

Problem: Accessing the app from a Cloudflare tunnel URL while the backend points to localhost. Solution - Option 1 (Recommended for development): Access the app from localhost instead:

http://localhost:5173

Solution - Option 2 (For testing on multiple devices): Tunnel both frontend and backend:

# Terminal 3 - Backend Tunnel
cloudflared tunnel --url http://localhost:3001

# Terminal 4 - Frontend Tunnel  
cloudflared tunnel --url http://localhost:5173

Then update your .env files with the tunnel URLs:

# main/frontend/.env
VITE_API_BASE=https://your-backend-tunnel.trycloudflare.com

# main/server/.env
FRONTEND_URL=https://your-frontend-tunnel.trycloudflare.com/

OAuth & Authentication Issues

Error: “Invalid state or code”

This OAuth error occurs when the redirect URI doesn’t match the configuration in HubSpot.

Solution:

Check your backend .env file:

HUBSPOT_REDIRECT_URI=http://localhost:3001/oauth/hubspot/callback

Verify HubSpot app settings:
- Go to HubSpot: Settings → Integrations → Private Apps
- Open your app
- Check that Redirect URL is exactly: http://localhost:3001/oauth/hubspot/callback
- No trailing slash, exact port number
For Cloudflare tunnels:
- Update redirect URI to your tunnel URL
- Update it in both HubSpot app settings and .env

The redirect URI must match character-for-character between HubSpot and your .env file.

Token Error in `/api/forms`

Problem: API calls fail with authentication errors after OAuth. Solution:

Verify OAuth flow completed:
- You should see “Connected” status in the UI
- Check browser console for connection confirmation
Check backend logs:
- Look for token storage confirmation
- Verify token was successfully retrieved
Re-authenticate:
- Click “Cerrar sesión” (Logout)
- Click “Connect to HubSpot” again
- Complete OAuth flow
Verify required scopes:

# main/server/.env
HUBSPOT_SCOPES=forms content forms-uploaded-files

HubSpot Integration Issues

Problem: After connecting, the form selector dropdown remains empty. Troubleshooting steps:

Check browser console (F12):
- Look for failed API requests
- Check for JavaScript errors
Verify your HubSpot account has forms:
- Log into HubSpot
- Go to Marketing → Lead Capture → Forms
- Ensure at least one form exists
Check backend logs:
- Look for /api/forms request
- Verify response contains forms array
Verify scopes:
- Ensure forms scope is included in HUBSPOT_SCOPES
- Re-authenticate if you recently added the scope

Forms Not Loading Fields

Problem: Selected form doesn’t display fields in the palette. Solution:

Ensure form has fields:
- Check the form in HubSpot has actual fields defined
- Empty forms will show “Todos los campos están en uso”
Check field schema:
- Open browser console
- Look for schema loading errors
- Verify field data structure is valid

Module Generation & Export Issues

Module Generation Fails

Problem: Clicking “Generar Módulo” produces an error. Common causes:

Empty layout:
- Ensure you have at least one field in the canvas
- Add fields from the palette before generating
Missing required fields:
- Required fields (marked with ⭐) must be in the layout
- Check validation warnings
Browser compatibility:
- Use a modern browser (Chrome, Firefox, Safari, Edge)
- Ensure JavaScript is enabled

Solution:

Verify all required fields are added to the canvas
Check browser console for specific errors
Try refreshing the page and rebuilding the layout

ZIP Download Not Working

Problem: “Descargar Módulo” button doesn’t download the file. Solution:

Check browser download settings:
- Ensure downloads are not blocked
- Check your Downloads folder
Try different browser:
- Test in Chrome/Firefox if using Safari
- Some browsers handle blob downloads differently
Check browser console:
- Look for download-related errors
- Verify ZIP generation completed

Environment & Configuration Issues

Missing Environment Variables

Problem: Server crashes with “Missing env var” error. Solution: Ensure all required variables are set: Backend (main/server/.env):

PORT=3001
HUBSPOT_CLIENT_ID=your-client-id
HUBSPOT_CLIENT_SECRET=your-client-secret  
HUBSPOT_REDIRECT_URI=http://localhost:3001/oauth/hubspot/callback
FRONTEND_URL=http://localhost:5173/
HUBSPOT_SCOPES=forms content forms-uploaded-files

Frontend (main/frontend/.env):

VITE_API_BASE=http://localhost:3001

Never commit .env files to version control. Use .env.example as a template.

Port Already in Use

Problem: Backend fails to start with “Port 3001 already in use”. Solution: Option 1 - Kill the existing process:

# Linux/Mac
lsof -ti:3001 | xargs kill -9

# Windows
netstat -ano | findstr :3001
taskkill /PID <PID> /F

Option 2 - Use a different port:

# main/server/.env
PORT=3002

Also update frontend configuration:

# main/frontend/.env
VITE_API_BASE=http://localhost:3002

And HubSpot redirect URI:

# main/server/.env
HUBSPOT_REDIRECT_URI=http://localhost:3002/oauth/hubspot/callback

Build & Compilation Errors

TypeScript Compilation Errors

Problem: Build fails with TypeScript errors. Solution:

Ensure dependencies are installed:

cd main/server
npm install

cd ../frontend  
npm install

Check TypeScript version:

npx tsc --version
# Should be 5.5.4 or higher

Clean and rebuild:

rm -rf node_modules package-lock.json
npm install
npm run build

Module Import Errors

Problem: “Cannot find module ‘shared’” or similar errors. Solution: The shared package is a local workspace dependency. Install from the project root:

cd "HubSpot Form builder"
npm install

Or install in each workspace:

cd main/shared
npm install

cd ../server
npm install

cd ../frontend
npm install

Drag & Drop Issues

Fields Not Draggable

Problem: Cannot drag fields from palette or within canvas. Solution:

Browser compatibility:
- Use Chrome, Firefox, Safari, or Edge (latest versions)
- Disable browser extensions that might interfere
Check console for errors:
- Open DevTools (F12)
- Look for dnd-kit related errors
Verify field is available:
- Field must be in palette to drag from there
- Field must be in canvas to reorder

Cannot Drop Field / Drop Zones Not Appearing

Problem: Drop zones don’t highlight or field doesn’t drop. Solution:

Row is full:
- Maximum 3 fields per row
- Create a new row or drop in a different position
Field already in use:
- Each field can only appear once in the layout
- Check if field is already placed elsewhere
Drop in correct zone:
- Top 20% of field = new row above
- Center = add to same row
- Bottom 20% = new row below

Performance Issues

Slow Performance / Lag

Problem: Application is slow or unresponsive. Solution:

Large forms:
- Forms with 50+ fields may be slower
- Consider splitting into multiple forms
Browser performance:
- Close unnecessary browser tabs
- Clear browser cache
- Restart browser
Check system resources:
- Ensure adequate RAM available
- Close other applications

Debugging Tips

Enable Detailed Logging

Backend logging:

// main/server/src/index.ts
console.log('Request:', req.method, req.path);
console.log('Headers:', req.headers);
console.log('Body:', req.body);

Frontend logging:

// Check store state
console.log('Layout:', useLayoutStore.getState());
console.log('Schema:', schema);

Check Browser Console

Open DevTools: Press F12 or right-click → Inspect
Go to Console tab
Look for:
- Red error messages
- Failed network requests (4xx, 5xx)
- JavaScript exceptions
Check Network tab for API calls

Verify Server Responses

Use curl or Postman to test backend endpoints:

# Check connection status
curl http://localhost:3001/oauth/hubspot/status

# Test forms endpoint (after auth)
curl http://localhost:3001/api/forms

Reset Application State

If issues persist, reset the application:

Clear browser storage:
- Open DevTools → Application tab
- Clear Local Storage and Session Storage
- Refresh page
Restart servers:
- Stop both frontend and backend (Ctrl+C)
- Restart both servers
Re-authenticate:
- Logout from HubSpot connection
- Complete OAuth flow again

Getting Help

Still Having Issues?

If you’re still experiencing problems after trying these solutions:

Check existing GitHub issues:
- Search for similar problems
- Check if issue is already reported
Create a new issue:
- Go to the GitHub repository
- Click “Issues” → “New Issue”
- Provide:
  - Detailed description of the problem
  - Steps to reproduce
  - Error messages (console logs)
  - Environment details (OS, Node version, browser)
  - Screenshots if applicable

Include diagnostic information:

# Node and npm versions
node --version
npm --version

# Check environment variables (sanitized)
cat main/server/.env | grep -v SECRET | grep -v CLIENT_ID

Documentation: For more information, check:

Quick Reference - Setup guide
Development Guide - Development workflow
FAQ - Frequently asked questions

Support

Troubleshooting

Troubleshooting

Connection Issues

Error: “localhost refused to connect”

Error: “Not allowed by CORS”

CORS Error: “Loopback address space blocked”

OAuth & Authentication Issues

Error: “Invalid state or code”

Token Error in `/api/forms`

HubSpot Integration Issues

Forms Not Loading Fields

Module Generation & Export Issues

Module Generation Fails

ZIP Download Not Working

Environment & Configuration Issues

Missing Environment Variables

Port Already in Use

Build & Compilation Errors

TypeScript Compilation Errors

Module Import Errors

Drag & Drop Issues

Fields Not Draggable

Cannot Drop Field / Drop Zones Not Appearing

Performance Issues

Slow Performance / Lag

Debugging Tips

Getting Help

Still Having Issues?

Build docs developers (and LLMs) love

Support

​Troubleshooting

​Connection Issues

​Error: “localhost refused to connect”

​Error: “Not allowed by CORS”

​CORS Error: “Loopback address space blocked”

​OAuth & Authentication Issues

​Error: “Invalid state or code”

​Token Error in /api/forms

​HubSpot Integration Issues

​Dropdown Not Populating with Forms

​Forms Not Loading Fields

​Module Generation & Export Issues

​Module Generation Fails

​ZIP Download Not Working

​Environment & Configuration Issues

​Missing Environment Variables

​Port Already in Use

​Build & Compilation Errors

​TypeScript Compilation Errors

​Module Import Errors

​Drag & Drop Issues

​Fields Not Draggable

​Cannot Drop Field / Drop Zones Not Appearing

​Performance Issues

​Slow Performance / Lag

​Debugging Tips

​Getting Help

Still Having Issues?

Build docs developers (and LLMs) love

Troubleshooting

Connection Issues

Error: “localhost refused to connect”

Error: “Not allowed by CORS”

CORS Error: “Loopback address space blocked”

OAuth & Authentication Issues

Error: “Invalid state or code”

Token Error in `/api/forms`

HubSpot Integration Issues

Dropdown Not Populating with Forms

Forms Not Loading Fields

Module Generation & Export Issues

Module Generation Fails

ZIP Download Not Working

Environment & Configuration Issues

Missing Environment Variables

Port Already in Use

Build & Compilation Errors

TypeScript Compilation Errors

Module Import Errors

Drag & Drop Issues

Fields Not Draggable

Cannot Drop Field / Drop Zones Not Appearing

Performance Issues

Slow Performance / Lag

Debugging Tips

Getting Help