Skip to main content

Troubleshooting

Quick solutions to common RowOps issues.

Installation Issues​

"Cannot find module '@rowops/importer'"​

Cause: Package not installed or node_modules corrupted.

Solution:

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

"Module not found: Can't resolve 'react'"​

Cause: React is a peer dependency and must be installed.

Solution:

npm install react react-dom

WASM binary not found (headless)​

Cause: WASM file cannot be located in Node.js environment.

Solution:

await initHeadless({
  projectId: "...",
  secretKey: "...",
  wasmPath: require.resolve("@rowops/engine-wasm/wasm"),
});

Or set environment variable:

ROWOPS_WASM_PATH=/path/to/rowops_wasm_bg.wasm

For edge/serverless environments, pass wasmBytes directly and supply a custom fileAdapter.

Authentication Issues​

"Domain not authorized"​

Cause: Your domain is not in the allowed domains list for your publishable key.

Solution:

  1. Go to Dashboard → Project → Domains
  2. Add your production domain (e.g., app.yourcompany.com)
  3. Wait a few seconds for propagation

Note: localhost is always allowed for development.

"Invalid publishable key"​

Cause: The key is malformed, revoked, or belongs to a different project.

Solution:

  1. Check the key starts with pk_
  2. Verify the key in Dashboard → Keys
  3. Generate a new key if needed
  4. Ensure you're using the correct project's key

"License expired"​

Cause: Your subscription has expired.

Solution:

  1. Go to Dashboard → Billing
  2. Update your payment method or renew subscription
  3. Contact support if you believe this is an error

"Schema not found"​

Cause: The schemaId doesn't match any schema in your project.

Solution:

  1. Go to Dashboard → Schemas
  2. Verify the schema exists and copy the exact ID
  3. Schema IDs are case-sensitive

File Parsing Issues​

"Parser error: Unexpected end of input"​

Cause: File is corrupted, truncated, or has encoding issues.

Solution:

  1. Open the file in Excel/Google Sheets and re-export as CSV
  2. Ensure the file is complete (not truncated during upload)
  3. Check for special characters or binary content

"Invalid file format"​

Cause: File extension doesn't match content, or format is unsupported.

Solution:

  1. Verify file opens correctly in native application
  2. Re-save in a supported format (CSV, XLSX)
  3. Don't rename file extensions manually

"Encoding error"​

Cause: File uses non-UTF-8 encoding.

Solution:

  1. Open in a text editor
  2. Save as UTF-8
  3. In Excel: Save As → CSV UTF-8 (Comma delimited)

Large file causes browser crash​

Cause: File exceeds browser memory limits.

Solution:

  1. Use streaming callbacks instead of materializing all rows at once:
<RowOpsImporter
  onExportChunk={(chunk, progress) => {
    // Process in chunks
  }}
  onExportComplete={(summary) => {
    // Done
  }}
/>
  1. Split file into smaller chunks before upload
  2. Consider using headless mode for very large files

Validation Issues​

All rows show as invalid​

Cause: Schema mismatch or column mapping issues.

Solution:

  1. Check that source columns are mapped to schema fields
  2. Verify required fields have data
  3. Check data types match schema (numbers, dates, etc.)
  4. Review sample data in the column mapper

"Required field missing" for filled cells​

Cause: Data appears empty after trimming, or uses whitespace-only values.

Solution:

  1. Check for cells with only spaces
  2. Remove leading/trailing whitespace from data
  3. Check for hidden characters (copy-paste from PDF can add these)

Regex validation failures​

Cause: Values don't match the pattern, or pattern is too strict.

Solution:

  1. Test your regex at regex101.com
  2. Common issues:
    • Anchors: Use ^...$ to match entire string
    • Case sensitivity: Use (?i) for case-insensitive
    • Special characters: Escape ., +, *, etc.

Enum validation failures​

Cause: Values don't exactly match allowed options.

Solution:

  1. Check for case differences (Active vs active)
  2. Check for leading/trailing whitespace
  3. Update enum values in schema if appropriate

UI/Rendering Issues​

Importer doesn't appear​

Cause: Server-side rendering issue (common in Next.js).

Solution (Next.js App Router):

"use client";
import { RowOpsImporter } from "@rowops/importer";

Solution (Next.js Pages Router):

import dynamic from "next/dynamic";

const RowOpsImporter = dynamic(
  () => import("@rowops/importer").then((m) => m.RowOpsImporter),
  { ssr: false }
);

Component renders but nothing happens on file drop​

Cause: Missing required props or JavaScript errors.

Solution:

  1. Check browser console for errors
  2. Verify all required props are provided:
    • projectId
    • schemaId
    • publishableKey
  3. Check that at least one callback is provided (onComplete or streaming callbacks)

Styles look broken​

Cause: Tailwind or CSS conflicts.

Solution:

  1. Ensure Tailwind is configured (if using Tailwind)
  2. Check for CSS that might override component styles
  3. Wrap importer in an isolated container if needed

Dark mode doesn't work​

Cause: ThemeProvider not configured.

Solution:

import { ThemeProvider } from "@rowops/importer";

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  <RowOpsImporter {...props} />
</ThemeProvider>

Data Export Issues​

onComplete never fires​

Cause: User didn't complete the full import flow.

Solution:

  1. Ensure users complete: Upload → Map → Validate → Export
  2. Check for blocking validation errors
  3. Verify the callback is defined correctly

onComplete shows zero rows​

Cause: All rows failed validation.

Solution:

  1. Check onComplete for the summary object
  2. Review validation errors
  3. Ensure data matches schema requirements

Exported data is missing columns​

Cause: Columns weren't mapped during import.

Solution:

  1. Check column mapping step
  2. Ensure all desired columns are mapped
  3. Unmapped columns are not included in output

Performance Issues​

Import is very slow​

Cause: Large file or unoptimized processing.

Solution:

  1. Use streaming mode for large files:
onExportIpcChunk={async (bytes, index) => { /* ... */ }}
  1. Reduce file size if possible (remove unnecessary columns)
  2. For very large files (>500K rows), use headless mode

Browser becomes unresponsive​

Cause: Memory pressure from large dataset.

Solution:

  1. Avoid materializing full datasets in JavaScript
  2. Use onExportChunk or onExportIpcChunk for streaming
  3. Process data on the server instead of browser

Memory usage keeps growing​

Cause: Data not being garbage collected.

Solution:

  1. Clear references to imported data after processing
  2. Use streaming callbacks that don't retain data
  3. Refresh page between large imports if needed

Headless/Node.js Issues​

"Headless runtime not initialized"​

Cause: runHeadlessJob called before initHeadless.

Solution:

await initHeadless({ projectId, secretKey }); // Must be first
const result = await runHeadlessJob({ ... });

License validation fails in CI/CD​

Cause: Network restrictions blocking /api/license/verify.

Solution: Allow network access for strict mode. For testing only, use demo mode:

await initHeadless({
  projectId,
  secretKey,
  licenseMode: "demo", // 100 row limit, watermark
});

Output file is empty​

Cause: All rows failed validation.

Solution:

  1. Check result.manifest.totals.invalidRows
  2. Review result.snapshot.validation.errorGroups
  3. Adjust schema if validation is too strict

Tier/Limit Issues​

"Row limit exceeded"​

Cause: File exceeds your plan's row limit.

Solution:

TierRow Limit
Free1,000
Pro100,000
Scale1,000,000
EnterpriseUnlimited
  1. Split file into smaller chunks
  2. Upgrade to higher tier

If you are using the default stop_with_warning policy, parsing stops at the limit and emits ROW_LIMIT_REACHED with skipped row metadata.

"Feature not available"​

Cause: Feature requires a higher tier.

Solution:

  1. Check feature availability
  2. Upgrade to access the feature
  3. Use alternative approaches available on your tier

Getting Help​

If your issue isn't covered here:

  1. Check error codes - See Error Codes Reference
  2. Copy error details - Use the "Copy Error Details" button in error UI
  3. Support - Email support@rowops.dev

When contacting support, include:

  • Error code and message
  • Browser/Node.js version
  • Steps to reproduce
  • File characteristics (format, size, approximate row count)