Common Issues

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

I cannot log in with my email and password#

Check your email address — Make sure you are using the exact email address associated with your account. Addresses with a + alias (e.g., you+lift@example.com) cannot log in to OpenBoxes directly — see Why doesn't OpenBoxes Lift accept email addresses with + aliases? in the FAQ.
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 (portal only) — After 5 failed sign-in attempts at the portal or auth.openboxes.cloud, the account is locked temporarily; the wait starts at 1 minute and grows with each further failure, to a maximum of 15 minutes. Wait and try again. The OpenBoxes login page on your instance has no lockout — repeated failures there simply fail.

"SSO" on Lift means the portal-to-instance bridge: clicking Launch in the customer portal signs you straight into your OpenBoxes instance. Signing in with Google, Microsoft, or GitHub is a separate feature called third-party sign-in (see below).

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.

Third-party sign-in is available for individual accounts on every plan; it is not organization SSO/SAML, which is not available on any plan today. If the provider's button fails, sign in with your email and password instead, then retry the provider once its own outage (check the provider's status page) has cleared.

My session keeps expiring#

Your OpenBoxes instance signs you out after 2 hours without activity. The customer portal at app.openboxes.cloud signs you out after 14 days without activity, and always after 30 days. If you are being logged out sooner than that:

Ensure your browser is not blocking cookies for openboxes.cloud.
Disable browser extensions that clear cookies automatically.

Performance Issues#

Pages are loading slowly#

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

I am getting timeout errors#

Timeout errors (504 Gateway Timeout) typically occur during:

Large data exports — Exporting thousands of records takes time. Try exporting smaller date ranges.
Bulk imports — Very large CSV imports may exceed request timeouts. If an import times out, split the file into smaller batches and import them in sequence.
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.

Data Issues#

My CSV import failed#

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 quantities do not match what I expect#

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.

Browser Compatibility#

OpenBoxes looks broken or features are missing#

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).

File downloads are not working#

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.

Still Need Help?#

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