Troubleshooting

Common issues and solutions when working with Kraal.

Bank Feeds

Bank feed not syncing

• Check the Plaid connection — Go to Settings > Integrations and verify the bank connection is active.
• Re-authenticate — Banks may require periodic re-authorization. Look for a "reconnect" prompt in the integration status.
• Check account selection — Ensure the correct accounts are selected for sync.
• Review sync logs — Check the logs for specific error messages about the feed.

Transactions missing from Banking view

• Allow sync time — Bank feeds sync on a recurring schedule (approximately every 15 minutes). Recent transactions may not appear immediately.
• 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.

QuickBooks

QuickBooks sync fails

• Check connection — Verify the QuickBooks connection is active in Settings > Integrations.
• Check permissions — Ensure the QuickBooks account has the necessary access permissions.
• Review logs — Check the Logs tab for specific error messages.
• Reconnect — Try disconnecting and reconnecting the QuickBooks integration.

Partial sync / missing data

• Check the Mappings tab — Review what has been successfully imported and what hasn't.
• Re-run sync — Some entities may fail on first attempt. Re-running often resolves transient issues.
• Contact support — If specific entity types consistently fail to sync.

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 being finished 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

• Test connection — Use the "Test ERPNext Connection" button in Settings > Clients.
• Check instance status — Verify the client's ERPNext instance is accessible.
• Contact support — If connection tests fail persistently.

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

• Check connection — use "Test ERPNext Connection" in Settings > Clients to verify connectivity.
• Sync manually — trigger a manual sync from the Inventory workspace if automatic sync has stalled.
• 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.

Command Center

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.