Documentation

Troubleshooting & FAQ

Quick answers to the issues that come up most often. If your problem isn’t here, check the relevant feature page in the sidebar — most pages have a “common issues” section near the bottom.

Sync

Sync badge stuck on Pending

A few possible causes:

  • No network. Check the Offline badge in the page header. The sync runs as soon as connectivity returns.
  • Validation errors. Records with red errors don’t sync. Open the affected drillhole, clear the errors (see Fix Validation Errors), and the next sync uploads them.
  • A very large operation. Bulk imports can sit in Pending for several 30-second cycles while the engine pages through 5,000 rows at a time. Let it run.
  • Server-side issue. Rare, but if Pending persists for many minutes with a stable network, sign out (only if you have nothing unsynced) and back in to reset the local sync state. Do not sign out if there’s anything you can’t lose — sign-out clears local data.

Conflict badge appeared

A conflict means the same record was modified locally and on the server. Blue Butterfly resolves it automatically: local wins, the record flips back to Pending, and re-uploads. You don’t have to do anything. If a conflict persists for more than one sync cycle, it’s worth a sign-in/sign-out (with everything else synced first) to reset state.

”I signed out and lost my data”

Sign-out clears local IndexedDB. This is by design — see Offline & Sync. Anything that was Pending at sign-out is gone.

What you can recover:

  • Synced data is safe — it’s in the cloud. Sign back in and it’ll re-download.
  • Pending data is gone unless you have a backup. Always confirm Synced badges before signing out.

Imports

”Hole ID column not detected”

The wizard scans for common aliases (HoleID, hole_id, DHID, DrillholeID). For unusual names, set the column manually in the import wizard’s step 3.

Many rows rejected

Common causes:

  • Hole ID values don’t match existing drillhole names. Check casing and formatting (DDH-001 vs DDH001 vs ddh-001). Either rename in the source file, or run a Collar import first to create the missing holes.
  • Validation rule failures. Open a sample of the imported rows and review red cells. Either fix the source data or relax the rule (see Validation Rules).
  • Type mismatches. A number column receiving text values fails. Check decimal separators (commas vs dots), units, and special characters.

Source values must match the dropdown options exactly, including capitalisation. granite is rejected if your options are Granite, Basalt, …. Either standardise the source file or add lowercase versions to the dropdown options list.

Re-imported and now I have duplicates

Imports are bulk inserts, not upserts. Re-importing a file creates duplicate rows. To clean up: delete the duplicates manually, or delete all rows in the table and re-import once. To prevent next time, see Import Overview → Duplicates.

Validation

Can’t save — but no cells look red

A few cases:

  • Unconfirmed edit. Press Enter or Tab to commit the cell first.
  • Formula column shows ERROR. Even though formulas are read-only, a formula error blocks save. Find the upstream cell whose value is making the formula fail (divide by zero, undefined column, etc.) and fix it.
  • Header counter says errors. Click the counter — the spreadsheet scrolls to the first error you missed.

A formula cell shows ERROR

The expression failed to evaluate. Common causes:

  • Divide by zero — a referenced denominator is 0
  • Undefined column — the formula references a column name that doesn’t exist (e.g., typo, or column was renamed/deleted)
  • Syntax error — invalid mathjs syntax

Fix the expression in Templates → Data Tables, or fix the upstream value.

3D Viewer

Holes don’t render

The viewer needs at least Easting, Northing, and Elevation mapped. Open the mapping dialog (Settings in the viewer header) and confirm each is set to a collar field that holds real values. See 3D Viewer.

Holes plot in the wrong place

Two common culprits:

  • X/Y axis swap. Easting (X) and Northing (Y) might be reversed. Check the mapping.
  • Mixed coordinate systems. All holes must be in the same projection. The viewer doesn’t reproject. Split projects if you have multi-zone data.

Holes plot upward

Dip-sign issue. Mining convention is negative dip = downhole. If your data uses positive-down or inclination-from-vertical, flip the sign in your data or in the dip column itself. See 3D Viewer.

PWA / Installation

”Install” icon doesn’t appear in Chrome

A few cases:

  • You’re on an unsupported browser. Chrome and Edge support PWA install. Safari uses Add to Home Screen instead. Firefox does not currently support installable PWAs.
  • The site is already installed. Look in your app launcher — Blue Butterfly may already be there.
  • The install prompt was dismissed. Some browsers cache the dismissal. Clear site data for bluebutterfly.app and revisit.

See Install as an App for the full flow.

Templates

”I deleted a column by accident”

Column deletion is immediate and removes data from every drillhole. There’s no undo button for this.

What you can do:

  • Restore from a backup (see Backup & Restore) if you have one
  • Re-create the column in Data Tables — the historical data is gone, but new rows from now on can be populated again

This is why we recommend regular backups, especially before destructive schema changes.

”Can I rename a column?”

Renaming a column changes its identifier everywhere — formulas, validation rules, exports, imports. If the column is referenced by a formula in another column, the formula will break unless you also update the reference.

In general, renaming is supported but disruptive. Consider whether you can live with the existing name before changing it.

Account & Access

”A collaborator can’t see the project”

A few checks:

  • Email exact match. They must sign in with the exact email you added them under.
  • They’ve signed in once after being added. Access is granted on next sign-in, not retroactively.
  • System-level allowlist. In some restricted deployments, users must also be on a system allowlist. Contact your administrator. See System-Level Access.

”I can’t add a collaborator”

Only Owners can manage collaborators. Editors and Viewers don’t see the Add Collaborator button. See Collaborators & Roles.

”I locked myself out”

If you removed yourself as Owner of a project, you’ve lost access. Another Owner has to re-add you. If you were the only Owner, contact support — they can restore Owner access from server-side records.

Still stuck?

Bring along these details when you reach out:

  • The Project ID (UUID, visible in Project Settings)
  • A description of what you tried, including any error messages
  • A backup file if the issue is project-specific and not too sensitive to share

Most issues turn out to be one of the above. The rest get fixed faster with concrete details.