Common Issues

This guide covers the most frequent issues users encounter on OpenBoxes Lift and how to resolve them.

Check your email address --- Make sure you are using the exact email address associated with your account. Email addresses are case-sensitive in some configurations.
Reset your password --- Click the "Forgot password?" link on the login page. A reset link will be sent to your email. Check your spam folder if it does not arrive within a few minutes.
Check your instance URL --- Ensure you are logging in at the correct subdomain (e.g., yourorg.openboxes.cloud, not app.openboxes.cloud). The portal and OpenBoxes instances have separate login pages.
Account locked --- After multiple failed attempts, accounts are temporarily locked for 15 minutes. Wait and try again.

"Access denied" after IdP login --- Your identity provider authenticated you, but your account may not be assigned to the OpenBoxes application in your IdP. Contact your IT administrator to verify the assignment.
Redirect loop --- Clear your browser cookies for openboxes.cloud and auth.openboxes.cloud, then try again. If the issue persists, the SSO redirect URI may be misconfigured --- contact support.
"Invalid token" error --- The clock on your IdP server may be out of sync. OIDC tokens have a short validity window. Ensure your IdP server's time is synchronized via NTP.

Sessions time out after a period of inactivity (default: 30 minutes). If you are frequently being logged out:

Ensure your browser is not blocking cookies for openboxes.cloud.
Disable browser extensions that clear cookies automatically.
If you need longer sessions, Dedicated and Enterprise tiers support configurable session timeouts --- contact support.

Performance Issues

Slow page loads are usually caused by one of:

Cause	Symptoms	Fix
Large dataset rendering	Inventory pages with thousands of items lag	Use filters and search to narrow results before loading
Slow network connection	All pages load slowly, not just data-heavy ones	Test with fast.com --- OpenBoxes needs at least 1 Mbps
Browser cache	Pages seem stale or sluggish	Clear browser cache or try incognito mode
Browser extensions	Ad blockers or security extensions interfere	Disable extensions temporarily to test

Timeout errors (504 Gateway Timeout) typically occur during:

Large data exports --- Exporting thousands of records takes time. Try exporting smaller date ranges.
Bulk imports --- Large CSV imports may exceed request timeouts. Break files into batches of 500 rows or fewer.
Report generation --- Complex reports over large datasets can time out. Narrow the date range or filter criteria.

If timeouts persist, the system may be under heavy load. Check the System Status page for any ongoing issues.

Common causes of import failures:

Encoding --- Save files as UTF-8. Excel sometimes saves as Windows-1252, which corrupts special characters.
Column headers --- Headers must match the expected template exactly. Download a fresh template from the import page before editing.
Date formats --- Use YYYY-MM-DD format (e.g., 2025-03-15). Other formats like MM/DD/YYYY may be misinterpreted.
Duplicate entries --- If a product code already exists, the import may reject the row. Check for duplicates before importing.
Empty required fields --- Fields like product name and product code cannot be blank.

Tip: Test imports with a small file (5-10 rows) first to validate your format before uploading the full dataset.

Inventory discrepancies usually have one of these causes:

Pending transactions --- Shipments that are "shipped" but not yet "received" reduce the sending location's stock but do not increase the receiving location until receipt is confirmed.
Expired stock --- Depending on configuration, expired inventory may or may not be counted in stock-on-hand totals.
Multiple locations --- Verify you are viewing the correct warehouse or depot. Stock is tracked per location.
Recent adjustments --- Check the stock history for the product to see if any recent adjustments or corrections were made.

Use a supported browser --- Chrome, Firefox, Safari, or Edge (latest two versions). Internet Explorer is not supported.
Enable JavaScript --- OpenBoxes requires JavaScript. Ensure it is not disabled in your browser settings or blocked by a corporate policy.
Disable conflicting extensions --- Privacy extensions (uBlock Origin, Privacy Badger) sometimes block API requests that OpenBoxes needs. Add *.openboxes.cloud to your extension's allowlist.
Clear cache --- After an OpenBoxes update, your browser may cache old files. Hard refresh with Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).

If export files (CSV, PDF) are not downloading:

Check that your browser is not blocking pop-ups for openboxes.cloud.
Check your downloads folder --- some browsers silently download without a prompt.
Try a different browser to isolate whether it is a browser-specific issue.

If your issue is not covered here, see the Error Reference for specific error codes or Contact Support for direct assistance.