Xero Hubdoc Integration Sync and Publishing Errors

10-minute fixVerified for Xero 2025Easy difficulty

Quick Answer:

Xero Hubdoc sync and publishing errors occur when documents fail to upload to Hubdoc, won't publish to Xero, or show "stuck" status. Common causes include disconnected integration, missing chart of accounts mapping, duplicate document detection, archived accounts, or expired OAuth tokens. Fix by reconnecting Hubdoc to Xero, refreshing chart of accounts sync, and clearing failed publish queue.

What are Xero Hubdoc Sync Errors?

Xero Hubdoc integration errors prevent documents from syncing between Hubdoc (Xero's document management system) and Xero accounting software. These errors typically occur during document upload to Hubdoc, publishing processed documents to Xero, or syncing chart of accounts, contacts, and tax codes. Since Xero acquired Hubdoc in 2018 and integrated it deeply into Xero workflows, sync errors can disrupt automated invoice processing and expense management.

Error Hubdoc Sync/Publish: Document Upload, Sync, or Publishing Failure

Hubdoc cannot upload documents, sync chart of accounts from Xero, or publish processed transactions back to Xero accounting.

Symptoms:
  • •Documents stuck in "Processing" or "Publishing" status
  • •Error: "Unable to publish to Xero" or "Publish failed"
  • •Message: "Chart of accounts not synced" or "Account not found"
  • •Documents upload but won't publish to Xero
  • •Duplicate document warnings blocking publish
  • •Error: "Archived account" when publishing expenses
  • •Integration shows "Disconnected" or requires reconnection
  • •Contacts or tax codes not syncing from Xero
Resolution Steps:
  1. 1.
    Disconnect and reconnect Hubdoc integration in Xero
  2. 2.
    Sync chart of accounts in Hubdoc settings
  3. 3.
    Clear failed publish queue and retry
  4. 4.
    Unarchive required accounts in Xero
  5. 5.
    Review and approve duplicate detection warnings
  6. 6.
    Update document coding with valid accounts

Quick Fix for Hubdoc Sync Errors (10 Minutes)

Fastest Solution

  1. Log into Xero → Settings → Connected Apps
  2. Find "Hubdoc" in list → Click "Manage"
  3. Click "Disconnect" → Confirm disconnection
  4. Wait 30 seconds for full disconnection
  5. Click "Connect to Hubdoc" or "Add Hubdoc"
  6. Log into Hubdoc when prompted (authorize connection)
  7. In Hubdoc: Settings → Integrations → Xero
  8. Click "Sync Now" to pull latest chart of accounts, contacts, tax codes
  9. Wait 2-3 minutes for sync to complete
  10. Go to Documents tab → Find stuck documents
  11. Click "Publish" → Select correct accounts → Publish to Xero
  12. Verify documents appear in Xero as bills or expenses

Detailed Solution Steps

  • 1
    Verify Hubdoc Integration Connection Status

    Check if Hubdoc is properly connected to Xero:

    1. Log into Xero
    2. Click Settings (gear icon) → Connected Apps
    3. Scroll through connected apps list
    4. Find "Hubdoc" entry
    5. Check status - should show "Connected" with green indicator
    6. If shows "Disconnected", "Expired", or red indicator - needs reconnection
    7. Note the connection date - if older than 90 days, may need refresh
    8. Also check in Hubdoc:
    9. Log into Hubdoc → Settings → Integrations
    10. Verify Xero shows as "Connected"
    11. Check organization name matches your Xero org

    OAuth Token Expiration:

    Xero's OAuth tokens for connected apps expire periodically for security
    Disconnecting and reconnecting refreshes the token and resolves most sync errors
  • 2
    Disconnect and Reconnect Hubdoc Integration

    Refresh integration connection to clear authentication issues:

    1. In Xero: Settings → Connected Apps
    2. Find "Hubdoc" → Click "Manage" or click on Hubdoc row
    3. Click "Disconnect" or "Revoke Access" button
    4. Confirm disconnection when prompted
    5. Wait 30-60 seconds for complete disconnection
    6. Refresh the Connected Apps page
    7. Look for "Add Hubdoc" or "Connect to Hubdoc" option
    8. Click the connect button
    9. You'll be redirected to Hubdoc authorization page
    10. Log into Hubdoc with your credentials
    11. Review permissions requested (read/write access to transactions, contacts, accounts)
    12. Click "Authorize" or "Connect"
    13. Redirected back to Xero - should see Hubdoc as "Connected"

    Don't Delete Hubdoc Documents

    Disconnecting the integration does NOT delete your Hubdoc documents or data. It only removes the sync connection. Reconnecting restores access without data loss.
  • 3
    Sync Chart of Accounts in Hubdoc

    Pull latest accounts, contacts, and tax codes from Xero:

    1. Log into Hubdoc
    2. Click Settings (gear icon) in top right
    3. Select "Integrations" from left menu
    4. Click on "Xero" integration
    5. Look for "Sync Now" or "Refresh Data" button
    6. Click "Sync Now"
    7. Hubdoc pulls:
    8. Chart of accounts (expense accounts, asset accounts, liability accounts)
    9. Contacts (suppliers/vendors)
    10. Tax codes/rates
    11. Tracking categories (if enabled)
    12. Progress bar shows sync status
    13. Wait 2-5 minutes for completion (depends on data volume)
    14. Should see "Last synced: [current date/time]"
    15. Verify accounts appear when publishing documents

    Auto-Sync Schedule: Hubdoc automatically syncs with Xero every 24 hours. Manual sync forces immediate update if you've recently added accounts or contacts in Xero.

  • 4
    Clear Failed Publish Queue and Retry

    Resolve stuck documents in publishing queue:

    1. In Hubdoc, go to "Documents" tab
    2. Filter by status: "Failed to publish" or "Error"
    3. Select documents showing publish errors
    4. Click on document to open details
    5. Review error message (e.g., "Account not found", "Duplicate detected")
    6. If error is "Account not found":
    7. Click "Edit" on document
    8. Update account coding with valid account from dropdown
    9. Save changes
    10. If error is "Archived account":
    11. Go to Xero → Settings → Chart of Accounts
    12. Find archived account → Unarchive it
    13. Return to Hubdoc → Sync again
    14. After fixing issues, click "Publish" button
    15. Select "Publish to Xero"
    16. Document should publish successfully
  • 5
    Handle Duplicate Document Warnings

    Resolve duplicate detection blocking publish:

    1. Hubdoc shows warning: "Possible duplicate document detected"
    2. Click on document to review details
    3. Hubdoc shows potential matches (same vendor, similar date, similar amount)
    4. Review each suggested duplicate:
    5. If truly duplicate (same invoice uploaded twice) → Click "Mark as duplicate" → Don't publish
    6. If NOT duplicate (different invoice, coincidentally similar) → Click "Not a duplicate" → Proceed
    7. After confirming "Not a duplicate", publish option becomes available
    8. Click "Publish to Xero"
    9. Document publishes normally
    10. Hubdoc learns from your duplicate decisions over time

    Duplicate Detection in 2025

    Hubdoc enhanced duplicate detection in 2024-2025 using AI to prevent duplicate expense entries. While helpful, it sometimes flags legitimate documents as duplicates, requiring manual review.
  • 6
    Fix Archived Account Publish Errors

    Unarchive accounts needed for document publishing:

    1. Error message in Hubdoc: "Cannot publish - account is archived in Xero"
    2. Note which account name is mentioned in error
    3. Log into Xero
    4. Go to Accounting → Chart of Accounts
    5. In "Show" dropdown, select "Archived Accounts"
    6. Find the archived account mentioned in error
    7. Click "Options" dropdown next to account
    8. Select "Unarchive"
    9. Xero asks "Are you sure?" → Click "Yes, unarchive"
    10. Account moves back to active accounts
    11. Return to Hubdoc → Settings → Integrations → Xero
    12. Click "Sync Now" to pull updated account status
    13. Try publishing document again - should work now

    Alternative: Instead of unarchiving, you can edit the document in Hubdoc to use a different, active account. This is better if the archived account is no longer relevant.

  • 7
    Verify Document Processing and OCR Completion

    Ensure documents finish processing before publishing:

    1. In Hubdoc Documents tab, check document status column
    2. Status progression: Uploaded → Processing → Processed → Ready to Publish
    3. If stuck on "Processing" for more than 10 minutes:
    4. Click on document
    5. Verify file is a valid PDF, JPG, or PNG (not corrupted)
    6. Check file size - very large files (50MB+) take longer
    7. Poor quality scans may fail OCR - consider re-uploading higher quality
    8. If OCR extraction is incorrect:
    9. Click "Edit" on document
    10. Manually correct vendor, date, amount, account
    11. Hubdoc learns from corrections to improve future OCR
    12. After processing completes, "Publish" button becomes active
    13. Click "Publish to Xero"
    14. Document publishes as bill or expense in Xero
  • 8
    Check Xero Permissions and Subscription Status

    Verify you have required permissions and active subscription:

    1. Publishing to Xero requires "Standard" or "Advisor" user role
    2. In Xero: Settings → Users
    3. Find your user account
    4. Verify role shows "Standard" or "Advisor" (NOT "Read Only" or "Invoicing Only")
    5. If incorrect role, ask organization admin to upgrade your permissions
    6. Check Hubdoc subscription status:
    7. Hubdoc Settings → Billing
    8. Verify subscription is "Active" (not "Expired" or "Trial Ended")
    9. Some Xero plans include Hubdoc; others require separate subscription
    10. Check document limits:
    11. Free Hubdoc with Xero: 50 documents/month
    12. Paid Hubdoc: Unlimited documents
    13. If over limit, documents won't publish until next billing cycle or upgrade

    • Why Do Hubdoc Sync Errors Occur?

    Root Causes

    • Expired OAuth Token: Xero's security requires periodic reauthentication; OAuth token expired after 60-90 days, breaking integration connection
    • Chart of Accounts Out of Sync: Accounts created in Xero haven't synced to Hubdoc yet, causing "account not found" errors when publishing
    • Archived Accounts: Document coded to account that was archived in Xero, preventing publish until account is unarchived or recoded
    • Duplicate Detection: Enhanced AI duplicate detection in 2024-2025 flagging legitimate documents as potential duplicates, requiring manual review
    • OCR Processing Failure: Poor quality scans, handwritten documents, or corrupted files causing optical character recognition to fail
    • Insufficient Permissions: Xero user role set to "Read Only" or "Invoicing Only", lacking permission to create bills/expenses
    • Subscription Limitations: Free Hubdoc tier exceeded 50 documents/month limit, or subscription expired, blocking additional publishes
    • Network/API Timeout: Temporary Xero API outage or slow internet causing publish requests to timeout before completion

    How to Prevent Hubdoc Sync Errors

    Best Practices:

    • Sync chart of accounts manually after creating new accounts or contacts in Xero
    • Monitor connected apps status monthly - reconnect before OAuth tokens expire
    • Before archiving accounts in Xero, check Hubdoc for documents using those accounts
    • Upload high-quality scans (300+ DPI) to improve OCR accuracy and reduce processing failures
    • Review duplicate warnings promptly - don't let documents pile up in pending status
    • Ensure Hubdoc users have "Standard" role in Xero, not "Read Only" access

    Frequently Asked Questions

    What's the difference between Hubdoc sync errors and publish errors?

    Sync errors prevent Hubdoc from pulling chart of accounts, contacts, or tax codes FROM Xero (inbound data). Publish errors prevent Hubdoc from sending processed documents TO Xero as bills/expenses (outbound data). Both are usually caused by disconnected integration or expired OAuth tokens. Reconnecting the integration fixes both types of errors simultaneously.

    Will disconnecting Hubdoc delete my uploaded documents?

    No, disconnecting the Xero integration does NOT delete any documents stored in Hubdoc. Your documents, processing history, and settings remain intact. Disconnecting only severs the sync connection between Hubdoc and Xero. Reconnecting restores the link without data loss. However, documents published to Xero before disconnection remain in Xero permanently.

    How often does Hubdoc automatically sync with Xero?

    Hubdoc automatically syncs chart of accounts, contacts, and tax codes every 24 hours (once per day). This background sync ensures your account lists stay current. However, if you add new accounts in Xero and need them immediately in Hubdoc, use the "Sync Now" button in Hubdoc Settings → Integrations → Xero to force immediate synchronization without waiting for the automatic daily sync.

    Is Hubdoc free with my Xero subscription?

    Xero includes basic Hubdoc access with most paid plans, allowing 50 documents per month. For unlimited documents, advanced features, and multiple users, you need a paid Hubdoc subscription ($20-40/month depending on plan and region). Check your Hubdoc Settings → Billing to see your current plan limits. If you're hitting the 50-document limit and can't publish more documents, you'll need to upgrade or wait until next billing cycle.

    Related Resources

    Xero Integration Sync Error

    Fix general integration sync issues

    Archived Account Error

    Fix archived account transaction errors

    Invoice Not Sending

    Fix email and invoice delivery issues

    Hubdoc Setup Guide

    Complete integration configuration

    Need Professional Help?

    If you're still experiencing Hubdoc sync or publishing errors after following these steps, or need help with Xero integration configuration, document management automation, or chart of accounts optimization, our Xero specialists are here to help.

    Get Expert Support