Troubleshooting

Common issues and solutions when working with Kraal.

Bank Feeds

Bank feed not syncing

• Open guided setup — Use the client's banking readiness step first.
• Let Kraal retry — If the feed can be retried safely, Kraal handles it in the background.
• Reconnect only when prompted — Banks may require periodic re-authorization. Use the reconnect prompt when Kraal shows one.
• Use statement upload as fallback — If the client does not want Plaid or the bank feed cannot be completed, upload statements and continue onboarding.

Transactions missing from Banking view

• Allow sync time — Recently connected accounts may take time to deliver transactions.
• Check date range — Ensure you're viewing the correct date range in the Banking view.
• Verify account — Confirm the transactions are from an account that's connected to Plaid.

Bank Reconciliation

Smart matching not finding expected matches

• Verify entries exist — Ensure the corresponding payment entry or journal entry exists in ERPNext.
• Check amounts — Matching relies on amounts, references, and dates. Verify these align between the bank transaction and the accounting entry.
• Use AI assistance — Try "Help me reconcile the bank" in the AI assistant for ambiguous matches.
• Create the entry — If no matching entry exists, create it manually, then re-run reconciliation.

Auto-rules not triggering

• Check rule configuration — Verify auto-rules are set up correctly for the patterns you expect (bank fees, interest, etc.).
• Check transaction descriptions — Ensure the bank transaction descriptions match the keywords in your auto-rules.

Account Reconciliation

No subjects appear in the Reconciliation Hub

• Confirm scope — Check the selected client, entity, and period end.
• Ask an administrator to review setup — Reconciliation subjects and profiles must be configured before they appear.
• Do not treat an empty page as complete — The balance-sheet coverage summary, not the absence of rows, determines whether material subjects are accounted for.

A run is stale or signoff is blocked

• Refresh the run — Rerun after ledger activity, source documents, mappings, or item dispositions change.
• Review blockers — Clear missing or stale evidence, unexplained differences, overdue timing items, and client responses awaiting firm review.
• Check review roles — Preparer and reviewer responsibilities must follow your firm's segregation-of-duties policy.
• Use the current run — Do not sign a superseded or stale result.

A linked client request has a delivery issue

• Confirm the portal contact — Verify that the request is assigned to the intended recipient.
• Retry from the request workflow — Resolve the contact or delivery problem before retrying.
• Keep the reconciliation open — A sent notification is not proof of receipt, response, or acceptable evidence.

See Account Reconciliation for the full status and signoff guide.

QuickBooks

QuickBooks sync fails

• Open guided setup — Use the client's QuickBooks readiness step first.
• Let Kraal recover — Kraal retries recoverable sync failures and checks token health automatically.
• Reconnect only when prompted — If QuickBooks requires authorization again, Kraal shows a reconnect action.
• Use the repair queue — Open the client's QuickBooks integration detail and review the repair queue before making manual changes elsewhere.
• Contact support if blocked — If readiness stays blocked, use the support message so Kraal technical staff can inspect the sync context.

Partial sync / missing data

• Check the integration detail first — Review connection state, recent mirrored work, and the repair queue.
• Use guided repair when shown — If Kraal offers a guided repair path, use that instead of editing things manually first.
• Check the Mappings tab only when needed — Review what has been successfully imported and what still needs a business mapping decision.
• Re-run sync or retry from Kraal — Some entities fail on first attempt and then clear after retry.
• Contact support — If the same entity type fails repeatedly after Kraal's repair steps.

QuickBooks write-back needs repair

• Open the client's QuickBooks integration detail — This is the main place for repair and retry.
• Read the surfaced next step — Kraal will tell you whether the issue is connection health, mapping, account setup, or a dependency problem.
• Repair inside Kraal — Use the repair action, save the fix, then retry from Kraal so the audit trail stays intact.
• Check Daily Board or ChatIQ — Use those views to confirm whether the client still shows stale failures after repair.

See QuickBooks Parallel Work for the full operating model.

Gusto Payroll

Gusto connection fails

• Reconnect from Kraal — Open the client's Gusto integration detail and use the reconnect action.
• Check company access — Confirm the user signing in has access to the correct Gusto company.
• Protect credentials — Do not paste Gusto tokens, authorization codes, client secrets, or browser session details into support messages.

Payroll preview is blocked

• Refresh ERPNext options — Make sure Kraal has the latest account and cost center list.
• Review missing accounts — Use the suggested payroll account setup only after confirming account type and chart placement.
• Confirm accounting policy — Review journal style, cost center allocation, and reimbursement treatment before changing mappings.
• Preview again — Draft creation should only happen when Kraal shows the payroll journal is balanced and ready.

Draft creation or submit fails

• Open Review logs — The Gusto panel links to integration logs for preview, draft creation, and submit actions.
• Do not create duplicates — If a draft already exists for the payroll run, use that draft.
• Submit manually only — Kraal may create a draft Journal Entry, but a human must review and submit every payroll Journal Entry.

See Gusto Payroll Accounting for the full setup and operating guide.

Avalara Sales Tax

Avalara does not connect

• Check all four badges — API environment, account lifecycle, usage mode, and commit policy are separate. A trial may authenticate against the Production API while remaining development-only and uncommitted.
• Resume securely — if setup was interrupted, use Kraal's resume action to issue fresh one-time setup state.
• Re-enter the key only in Kraal — do not send a license key, token, setup link, or screenshot of credentials to support.
• Check company access — confirm the Avalara account can access the intended active company.

Company binding is blocked

• Verify the legal entity — one Avalara company can be bound to only one Kraal entity in the same environment.
• Do not choose a substitute company — resolve an existing or incorrect binding through the authorized setup flow.
• Check Production API versus Sandbox API — a company in one API environment cannot satisfy the other environment's setup.

Trial connection shows Production API

• Do not treat the badge as live approval — the trial should also show Trial account, Development use, and Commit disabled.
• Use fictional test data only — stay in the dedicated test entity and within the limit shown by Kraal.
• Expect uncommitted results — normal invoices and automated refunds remain blocked.
• Stop if the profile labels disagree — do not continue until the account purpose and usage mode are corrected.

Ship-from address is not ready

• Complete every address field — include street, city, region, postal code, and country.
• Review suggested corrections — accept an Avalara correction only after comparing it with the client's source record.
• Validate again after an edit — a changed address must be revalidated before invoice posting.

Invoice tax preview is missing or stale

• Check customer destination — use a complete ship-to address.
• Check item codes and classifications — ambiguous or unmapped lines may require review.
• Recalculate explicitly — changing a material invoice field invalidates the earlier preview; review the changes, then select Calculate Avalara tax or Recalculate Avalara tax.
• Do not add tax twice — remove a manually selected ERPNext tax template from an Avalara-enabled invoice.
• Check readiness — a connected account can still have blocking setup controls.

ERPNext posted but Avalara needs repair

• Do not recreate the invoice — Kraal retains an operation record and attempts to prove provider state before retrying.
• Use the surfaced repair action — retry or reconcile the existing operation.
• Escalate a locked transaction — a locked or previously reported provider record may require an authorized accounting correction.

Credit note or refund is blocked

• Start from the original invoice — this preserves provider transaction and line references.
• Select whole original lines — partial quantities and altered original references require individual review in the initial workflow.
• Review tax-inclusive credits individually — do not work around the blocker with a separate negative invoice.
• Reuse the existing credit note — if provider repair is needed, do not create a duplicate return.

Close reports unresolved sales tax

Open the Avalara reconciliation exception from Kraal and compare its invoice, transaction state, tax, and reversal lineage. Clear missing, duplicate, uncommitted, or mismatched records before completing tax readiness for close. A matched record confirms system agreement; it does not confirm filing or remittance.

A development trial or incomplete optional setup should not become a client close control. If one appears as a close blocker, stop and verify the four connection labels before changing accounting records.

See Avalara Sales Tax for the complete setup and operating guide.

Transactions

PDF upload fails or returns no transactions

• Check the file format — Use bank-generated PDFs, not scanned images. Kraal needs structured text to extract transactions.
• File size — Very large statements (100+ pages) may time out. Try splitting into smaller files.
• Password-protected PDFs — Remove the password before uploading.

AI categorization is inaccurate

• Map the vendor — Once you manually categorize a transaction, map the vendor so future transactions from the same payee are auto-categorized.
• Check the chart of accounts — If the correct account doesn't appear in suggestions, verify it exists in your client's COA.

Automated Close

Close period stuck or steps won't progress

• Check prerequisites — Steps are dependency-gated. A step won't start until its prerequisites are complete.
• Complete reconciliation — Many close steps depend on bank reconciliation and required account-reconciliation gates being complete for the period.
• Verify transactions posted — Ensure all transactions for the period have been posted to ERPNext.
• Check template — Ensure a close template is assigned to the client.

Close pack generation fails

• Ensure all required close period items are marked as complete.
• If the issue persists, contact support.

ERPNext Connection

ERPNext operations fail

• Open guided setup — Refresh client readiness first.
• Let Kraal verify — Kraal checks ERPNext connectivity and chart of accounts readiness automatically.
• Contact support — If readiness stays blocked after refresh.

ERPNext accounting dimensions error

If you see an error when refreshing accounting dimensions from ERPNext, this is a known issue being worked on. Contact support for assistance.

Exports

CSV export has missing data

• Review incomplete — Ensure all transactions are approved before exporting. Unapproved transactions are excluded.
• Vendor not mapped — Transactions without a vendor mapping may have blank vendor fields in the export.

QuickBooks import rejects the CSV

• Date format — QuickBooks expects dates in MM/DD/YYYY format. If your export uses a different format, check with your administrator.
• Duplicate detection — QuickBooks may flag transactions that were previously imported. This is normal if you're re-exporting.

Inventory

Items not syncing from ERPNext

• Open readiness — refresh the client's guided setup or inventory readiness state.
• Let Kraal retry — Kraal verifies ERPNext connectivity and retries recoverable sync work.
• Check item status — items must be enabled and not archived in ERPNext to appear in Kraal.

Stock levels don't match

• Check pending stock entries — unsubmitted stock entries won't update balances. Review the Stock Entries view for draft entries.
• Verify warehouse — ensure you're viewing the correct warehouse. Stock Balance shows quantities per warehouse.
• Review stock adjustments — check for recent adjustments that may have changed quantities.

Purchase or sales order errors

• Required fields — ensure all mandatory fields (item, quantity, rate, supplier/customer) are filled in.
• Item availability — for sales orders, verify sufficient stock exists in the selected warehouse.

E-commerce Integrations

Shopify or Amazon connection fails

• Re-authorize — go to Integrations, disconnect the store, and follow the authorization flow again.
• Check permissions — ensure the Shopify/Amazon account has the required API permissions.
• Review sync logs — check the integration detail page for specific error messages.

Orders not appearing

• Allow sync time — e-commerce data syncs on a recurring schedule. Recent orders may take a few minutes to appear.
• Check date range — verify you're viewing the correct date range.
• Check sync configuration — ensure the correct data types (orders, products, inventory) are enabled for sync.

Inventory quantities out of sync with store

• Trigger manual sync — use the sync button on the integration detail page.
• Check location mapping — verify that Shopify locations or Amazon warehouses are mapped to the correct Kraal warehouses.

ChatIQ and AI work

AI task stuck in "Running" state

• Wait briefly — complex tasks (reconciliation, report generation) may take several minutes.
• Check task detail — open the task to see if the AI is waiting for information or has encountered an issue.
• Cancel and retry — if a task has been running for an extended period with no progress, cancel it and launch a new one.

AI suggestions seem incorrect

• Provide more context — use the conversation panel to clarify your request or provide additional details.
• Check client data — AI suggestions depend on the quality of underlying data. Verify that the chart of accounts, vendor mappings, and transaction history are accurate.
• Review and correct — use the approval workflow to decline incorrect suggestions and provide feedback.

Skills or workflows not appearing

• Check client type — some skills are only available for clients with specific configurations (e.g., inventory skills require inventory to be enabled).
• Refresh the page — skills load dynamically. A page refresh may resolve display issues.

Dispatch

Not receiving alert emails

• Check email preferences — verify your notification schedule (immediate, daily, weekly) in Settings.
• Check spam folder — Dispatch emails may be filtered by your email provider.
• Verify policies — ensure you have active policies configured. No policies means no alerts.

Alerts firing for irrelevant items

• Refine your policies — adjust thresholds, account filters, or transaction patterns to reduce noise.
• Update watchlists — narrow your watchlists to focus on the specific clients or accounts that matter.

Getting help

If you're experiencing an issue not covered here, contact your Kraal administrator or reach out to support. See the FAQ & Troubleshooting page for the recommended escalation template.