Configuration Troubleshooting

This page addresses common issues encountered during QuickBooks integration configuration, including connection problems, credential errors, and settings issues.

Connection Issues

”Invalid Client Credentials” Error

Error Message: “Invalid client credentials” or “Authentication failed”

Possible Causes:

• Incorrect Client ID or Secret
• Extra spaces before/after credentials
• Truncated credentials (not copied fully)
• Wrong environment for credentials

Solutions:

1. Verify credentials are complete:

   • Client ID should be ~40-50 characters
   • Client Secret should be ~50-70 characters
   • Check no characters were cut off during copy/paste

2. Check for extra spaces:

   • Paste credentials into a text editor first
   • Verify no leading or trailing spaces
   • Copy again without spaces

3. Verify environment matches credentials:

   • Sandbox environment → Use Development Client ID & Secret
   • Production environment → Use Production Client ID & Secret
   • Check which section you copied from in Intuit portal

4. Regenerate credentials:

   • Go to Intuit Developer Portal → Keys & credentials
   • Click Regenerate or Rotate
   • Copy new credentials
   • Update in HubSpot settings

”Redirect URI Mismatch” Error

Error Message: “redirect_uri_mismatch” or “Redirect URI does not match”

Cause: The redirect URI is not configured in your Intuit Developer app

Solutions:

1. Add redirect URI to Intuit app:

   • Go to developer.intuit.com 
   • Navigate to your app → Keys & credentials
   • Scroll to Redirect URIs section
   • Click Add URI
   • Enter exactly:

     https://hubspot.structur.app/quickbooks/oauth-callback

   • Click Save

2. Verify exact match:

   • No trailing slash
   • All lowercase after domain
   • HTTPS (not HTTP)
   • No extra parameters or query strings

3. Check environment:

   • Add redirect URI in both Development and Production sections
   • Ensure it’s in the section matching your current environment

4. Wait and retry:

   • Changes may take 1-2 minutes to propagate
   • Refresh HubSpot settings page
   • Try connecting again

See Configure OAuth for detailed redirect URI setup.

OAuth Window Closes Immediately

Symptom: OAuth authorization window opens and closes within seconds

Possible Causes:

• Browser popup blocker
• Browser security settings
• Network/firewall blocking Intuit domains
• Invalid OAuth configuration

Solutions:

1. Allow popups:

   • Look for popup blocked notification in browser address bar
   • Click and select “Always allow popups from this site”
   • Retry connection

2. Try different browser:

   • Chrome, Firefox, Safari, or Edge
   • Disable extensions temporarily
   • Try incognito/private mode

3. Check firewall:

   • Ensure firewall isn’t blocking *.intuit.com domains
   • Temporarily disable VPN if using one
   • Check corporate network restrictions

4. Clear browser cache:

   • Clear cookies and cached data
   • Close all browser windows
   • Restart browser and retry

”You Don’t Have Permission to Authorize” Error

Error Message: “You don’t have permission” or “Access denied” during OAuth

Cause: Not signed in as QuickBooks Company Admin

Solutions:

1. Sign out of QuickBooks:

   • Close OAuth window
   • Go to QuickBooks.intuit.com 
   • Sign out completely

2. Sign in as Admin:

   • Use Company Admin or Primary Admin account
   • Not a standard user or bookkeeper

3. Verify admin status:

   • QuickBooks → Settings → Manage Users
   • Check your role is “Company Admin”
   • If not, ask Primary Admin for help

4. Retry connection:

   • Return to HubSpot settings
   • Click “Connect to QuickBooks” again
   • Should now work with admin account

Connection Times Out

Symptom: “Connection timeout” or OAuth flow never completes

Possible Causes:

• Slow network connection
• QuickBooks API temporarily unavailable
• Browser timeout
• Firewall blocking requests

Solutions:

1. Check network:

   • Verify stable internet connection
   • Try different network if possible
   • Disable VPN temporarily

2. Retry connection:

   • Wait 5 minutes
   • Refresh HubSpot settings page
   • Try connecting again

3. Check Intuit status:

   • Visit status.developer.intuit.com 
   • Verify QuickBooks API is operational
   • If outage, wait until resolved

4. Increase timeout:

   • Try different browser (some have longer timeouts)
   • Ensure fast network connection
   • Close other bandwidth-heavy applications

Settings Issues

Cannot Access Settings Page

Symptom: Settings page won’t load or shows “Access Denied”

Possible Causes:

• Not a Super Admin in HubSpot
• App not fully installed
• Browser issue

Solutions:

1. Verify Super Admin role:

   • HubSpot → Settings → Users & Teams
   • Check your role is “Super Admin”
   • If not, contact HubSpot administrator

2. Verify app installation:

   • Settings → Integrations → Connected Apps
   • QuickBooks Invoicing should be listed
   • If not, reinstall from Marketplace

3. Try different access method:

   • Via Connected Apps page
   • Via CRM card settings link
   • Direct URL if known

4. Clear browser cache:

   • Clear cookies and cache
   • Restart browser
   • Retry accessing settings

Default Settings Dropdowns Are Empty

Symptom: Tax code and product dropdowns show no options

Possible Causes:

• Not connected to QuickBooks yet
• QuickBooks company has no tax codes or products
• Connection lost
• API error

Solutions:

1. Verify connection:

   • Check Authentication tab shows “Connected”
   • If not connected, connect first
   • Defaults won’t load without connection

2. Check QuickBooks data:

   • Log into QuickBooks Online
   • Go to Taxes → Verify at least one tax code exists
   • Go to Sales → Products and Services → Verify at least one product exists

3. Create missing data in QuickBooks:

   • For tax codes: Taxes → Sales Tax → Set up tax or create non-taxable rate
   • For products: Sales → Products and Services → New → Create service or product

4. Refresh HubSpot settings:

   • Refresh the page (F5 or Ctrl+R)
   • Dropdowns should populate within 5 seconds
   • If still empty, disconnect and reconnect

Settings Won’t Save

Symptom: Click Save but settings don’t persist

Possible Causes:

• Network error
• Validation failure
• Not connected to QuickBooks
• Browser issue

Solutions:

1. Check connection:

   • Must be connected to QuickBooks before saving defaults
   • Verify Authentication tab shows “Connected”

2. Check for error messages:

   • Look for red error text below fields
   • Read error message for specific issue
   • Fix validation errors

3. Check network:

   • Verify stable internet
   • Check browser console for errors (F12 → Console tab)
   • Retry after network stabilizes

4. Try different browser:

   • Test in Chrome, Firefox, or Safari
   • Disable browser extensions
   • Try incognito mode

5. Verify selections:

   • Ensure you’ve selected valid options from dropdowns
   • Not leaving required fields empty
   • Click Save button (don’t just navigate away)

Environment and Credential Issues

Wrong Environment Selected

Symptom: Connection fails even though credentials look correct

Cause: Environment doesn’t match credentials

Solution:

1. Verify environment:

   • Check Environment dropdown in Authentication tab
   • Should show “Sandbox” or “Production”

2. Match credentials to environment:

   Environment	Use These Credentials
   Sandbox	Development Client ID & Secret
   Production	Production Client ID & Secret

3. Get correct credentials:

   • Intuit Developer Portal → Your App → Keys & credentials
   • Development section → For Sandbox
   • Production section → For Production

4. Update environment or credentials:

   • Either change environment to match credentials
   • Or get correct credentials for selected environment

See Environment Selection for detailed guide.

Production Keys Not Available

Symptom: Cannot find Production Client ID and Secret in Intuit portal

Cause: Production keys not yet generated

Solution:

1. Generate production keys:

   • Intuit Developer Portal → Your App → Keys & credentials
   • Scroll to Production section
   • Enter Privacy Policy URL (publicly accessible)
   • Enter EULA URL (publicly accessible)
   • Click Create Production Keys

2. Verify URLs:

   • Both must be HTTPS
   • Must be publicly accessible (not behind login)
   • Must load successfully
   • Cannot be localhost or internal URLs

3. If URLs are rejected:

   • Verify they’re accessible in incognito browser
   • Check for typos in URLs
   • Ensure HTTPS (not HTTP)
   • Make sure pages load without errors

See Get Credentials for details.

Connected to Wrong QuickBooks Company

Symptom: Connected but it’s the wrong QuickBooks company

Solution:

1. Disconnect:

   • Settings → Authentication tab
   • Click Disconnect

2. Reconnect:

   • Click Connect to QuickBooks
   • During OAuth, carefully select the correct company
   • Look for company name in the list
   • Double-check before clicking Authorize

3. Verify after connection:

   • Settings should display correct company name
   • If wrong again, repeat steps 1-2

Browser and Technical Issues

Settings Page Displays Incorrectly

Symptom: Layout broken, fields missing, or garbled display

Possible Causes:

• Browser cache corruption
• Browser compatibility
• CSS loading failure

Solutions:

1. Hard refresh:

   • Windows/Linux: Ctrl+Shift+R
   • Mac: Cmd+Shift+R

2. Clear browser cache:

   • Settings → Privacy → Clear browsing data
   • Select “Cached images and files”
   • Clear and reload page

3. Try supported browser:

   • Chrome (recommended)
   • Firefox
   • Safari
   • Edge

4. Disable browser extensions:

   • Ad blockers may interfere
   • Privacy extensions may block scripts
   • Disable extensions and retry

Changes Not Taking Effect

Symptom: Saved changes don’t appear in invoice creation

Possible Causes:

• Browser cache
• Settings not actually saved
• Modal not refreshed

Solutions:

1. Verify settings saved:

   • Return to Defaults tab
   • Check selections still show your choices
   • If not, settings didn’t save - try saving again

2. Hard refresh HubSpot:

   • Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
   • Clears cached data

3. Sign out and back in:

   • Sign out of HubSpot completely
   • Clear browser cache
   • Sign back in
   • Test invoice creation

4. Try different deal:

   • Open a different deal record
   • Click QuickBooks Invoices tab
   • Try creating invoice
   • Check if defaults appear

Getting Additional Help

Before Contacting Support

Gather this information:

• HubSpot account ID
• Environment selected (Sandbox or Production)
• Exact error message (screenshot if possible)
• Steps to reproduce the issue
• Browser and version
• Whether you’re a Super Admin in HubSpot
• Whether you’re a Company Admin in QuickBooks

How to Contact Support

Email: support@structur.app

Subject line format: “QuickBooks Integration - [Brief Issue Description]”

Include in email:

• Detailed description of issue
• Steps to reproduce
• Error messages
• Screenshots
• Information gathered above

Response time: Within 24 hours on business days

Common Error Messages

Advanced Troubleshooting

Browser Console Errors

To check for JavaScript errors:

1. Open browser console:

   • Windows/Linux: Ctrl+Shift+J or F12
   • Mac: Cmd+Option+J

2. Go to Console tab

3. Look for red error messages

4. Screenshot errors and send to support

Network Tab Analysis

To diagnose API issues:

1. Open browser DevTools (F12)

2. Go to Network tab

3. Reproduce the issue (e.g., click Connect)

4. Look for failed requests (red status codes)

5. Click failed request → Response tab

6. Screenshot error details for support

Preventive Measures

To Avoid Connection Issues

✅ Do:

• Copy credentials carefully (no truncation)
• Verify environment matches credentials
• Configure redirect URI before connecting
• Use Super Admin account in HubSpot
• Use Company Admin account in QuickBooks
• Test in Sandbox before Production

❌ Don’t:

• Mix up Development and Production credentials
• Skip redirect URI configuration
• Attempt connection without admin permissions
• Share credentials insecurely

To Avoid Settings Issues

✅ Do:

• Connect to QuickBooks before configuring defaults
• Ensure QuickBooks has tax codes and products
• Save settings after making changes
• Verify settings persist after saving

❌ Don’t:

• Try to configure defaults before connecting
• Assume empty dropdowns are a bug (check QuickBooks data)
• Navigate away without saving
• Forget to test after configuration

Next Steps

If Issues Resolved

1. Create Your First Invoice - Start using the integration
2. Best Practices - Optimize your workflow

If Issues Persist

1. Authentication Troubleshooting - Comprehensive auth troubleshooting
2. Contact Support - Get personalized help

Additional Resources

• Connect to QuickBooks - Connection guide
• Environment Selection - Sandbox vs Production
• Configure OAuth - Redirect URI setup
• Get Credentials - Finding Client ID and Secret