Troubleshooting

Solutions to common issues encountered when using MIMS SDK.

Installation Issues

Module not found errors

If you see errors like "Cannot find module '@mims/sdk-react'":

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

# Or with pnpm
rm -rf node_modules pnpm-lock.yaml
pnpm install

TypeScript errors after installation

Ensure your TypeScript version is compatible:

{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "node16"
    "esModuleInterop": true
  }
}

React version mismatch

If you see errors about invalid hook calls:

# Check for duplicate React installations
npm ls react

# If duplicates exist, dedupe
npm dedupe

Authentication Issues

"API key is required" error

Check these common causes:

1. Environment variable not set:

   # .env.local
   NEXT_PUBLIC_MIMS_API_KEY=pk_live_your_key_here

2. Wrong variable prefix: Next.js requires NEXT_PUBLIC_prefix for client-side variables.
3. Server not restarted: Restart your dev server after adding env vars.

"Invalid API key format" error

API keys must start with one of:

• pk_live_ - Production publishable key
• pk_test_ - Test publishable key
• sk_live_ - Production secret key (server only)
• sk_test_ - Test secret key (server only)

"API key validation failed" error

Possible causes:

• Key was revoked or deleted
• Key has expired
• Using test key with production URL (or vice versa)
• Network connectivity issues

PDF Loading Issues

PDF fails to load with CORS error

If your PDF is hosted on a different domain, ensure CORS headers are set:

// Required CORS headers on your PDF server
Access-Control-Allow-Origin: https://your-app.com
Access-Control-Allow-Methods: GET
Access-Control-Allow-Headers: Range

Solution: Use signed URLs from MIMS API or proxy the PDF through your backend.

PDF shows blank or fails silently

Enable debug mode to see detailed logs:

<MIMSProvider apiKey="..." debug={true}>
  {/* Check console for detailed logs */}
</MIMSProvider>

Common causes:

• URL returns 404 or other error
• PDF is password-protected (not supported)
• PDF is corrupted or malformed
• Content-Type header is not application/pdf

Large PDF takes too long to load

Optimize PDF loading:

// Show loading state while PDF loads
function DocumentViewer() {
  const [loading, setLoading] = useState(true);

  return (
    <>
      {loading && <LoadingSpinner />}
      <PDFViewer
        documentUrl={url}
        documentId={id}
        onDocumentLoad={() => setLoading(false)}
        onDocumentError={(err) => {
          setLoading(false);
          console.error(err);
        }}
      />
    </>
  );
}

Submission Issues

Submission fails with validation error

Ensure all required fields are filled:

<PDFViewer
  onBeforeSubmit={(payload) => {
    // Check for empty required fields
    const emptyRequired = payload.fields.filter(
      f => f.required && !f.value
    );
    
    if (emptyRequired.length > 0) {
      alert('Please fill all required fields');
      return false; // Cancel submission
    }
    
    return true;
  }}
  onSubmit={handleSubmit}
/>

Submission succeeds but callback not called

Make sure onSubmit returns a Promise if async:

// Correct - returns Promise
onSubmit={async (payload) => {
  await saveToBackend(payload);
  showSuccess();
}}

// Incorrect - doesn't await
onSubmit={(payload) => {
  saveToBackend(payload); // Missing await
  showSuccess(); // Called before save completes
}}

"Insufficient scopes" error on submit

Your API key needs the documents:write scope:

1. Go to Dashboard → API Keys
2. Edit your key or create a new one
3. Enable the documents:write scope
4. Update your environment variable with the new key

Signature Issues

Signature not appearing in submitted PDF

Ensure the signature data is captured correctly:

<PDFViewer
  onFieldValueChange={(fieldId, value) => {
    if (value.type === 'signature') {
      console.log('Signature captured:', {
        hasImageData: !!value.imageData,
        hasPathData: !!value.pathData,
      });
    }
  }}
/>

SignaturePad not responding to touch

Check for CSS issues that might block touch events:

/* Ensure touch events aren't blocked */
.signature-container {
  touch-action: none; /* Required for canvas touch */
}

/* Don't set pointer-events: none on parent elements */

Performance Issues

Slow initial load

The SDK lazy-loads the PDF library. Preload it for faster rendering:

// Preload PDF.js when user approaches document page
import { useEffect } from 'react';

function PreloadPDF() {
  useEffect(() => {
    // Trigger lazy load ahead of time
    import('pdfjs-dist');
  }, []);
  
  return null;
}

Memory issues with large documents

For documents with many pages, consider pagination:

// Only render visible pages (built-in behavior)
// The PDFViewer only renders the current page by default

// For custom implementations, use the store
const { currentPage, totalPages, goToPage } = useDocumentStore();

Debug Checklist

When reporting issues, please provide:

1. SDK version (npm ls @mims/sdk-react)
2. React version
3. Framework (Next.js, Vite, etc.) and version
4. Browser and version
5. Console errors (with debug mode enabled)
6. Network tab showing failed requests
7. Minimal reproduction code