Manual Error Reporting

Cluebase automatically catches React crashes and unhandled exceptions. But for errors you catch and handle gracefully (like failed API calls or validation errors), use the useCluebaseReport hook.

Coding Agent Prompt for Manual Error Reporting

Copy & paste this prompt into Cursor, Claude, ChatGPT, Copilot, or Antigravity to add manual error reporting to your project.

Add Cluebase manual error reporting to handle async operations, API failures, and caught exceptions in this project:
1. Ensure `cluebase-next` (or `cluebase-react`) is installed and `CluebaseProvider` is wrapping your application.
2. Import `useCluebaseReport`:
   `import { useCluebaseReport } from 'cluebase-next';` (or `'cluebase-react'`)
3. Initialize the hook in your component or custom hook:
   `const { reportError } = useCluebaseReport();`
4. Report caught errors silently inside your `try / catch` blocks or API response checks:
   `try { ... } catch (err) { await reportError(err as Error, { action: 'action_name', context: 'value' }); }`

Note: If you have web search capability, visit https://cluebase.dev/docs for detailed documentation and API reference.

When to use manual reportingUse reportError() when you catch an error but still want it logged to your dashboard.

Basic Usage

PaymentForm.tsx

import { useCluebaseReport } from 'cluebase-next';

function PaymentForm() {
    const { reportError } = useCluebaseReport();

    const handlePayment = async () => {
        try {
            const res = await fetch('/api/payments', { 
                method: 'POST' 
            });

            if (!res.ok) {
                // Report the API error to Cluebase
                const error = new Error(`Payment failed: ${res.status}`);
                await reportError(error, { 
                    action: 'payment',
                    statusCode: res.status 
                });
                
                alert('Payment failed. Please try again.');
            }
        } catch (err) {
            // Network errors
            await reportError(err as Error, { action: 'payment' });
            alert('Network error. Check your connection.');
        }
    };

    return <button onClick={handlePayment}>Pay Now</button>;
}

Adding Context

Pass additional context as the second argument to help with debugging.

tsx

await reportError(error, {
    action: 'user_signup',
    userId: user.id,
    email: user.email,
    formStep: 'payment',
});

Tagging the error type

Pass an errorType as the third argument so the AI explanation shown to the user (and the dashboard) reflects what actually happened, instead of a generic message.

tsx

await reportError(error, { action: 'checkout' }, 'payment_integration');

Available types: 'api_error', 'network_timeout', 'payment_integration', 'render_crash', 'component_crash', 'unhandled_rejection', 'global_error', 'generic'.

Automatic Fetch Classification

Instead of hand-rolling a fetch wrapper, use useCluebaseFetch, which automatically detects and reports API failures using the real HTTP status code and request host captured at the point of failure (not guessed from a stringified error message), so a failed Stripe call gets a payment-specific explanation and a 500 gets framed as "on our end."

Checkout.tsx

import { useCluebaseFetch } from 'cluebase-next';

function Checkout() {
    const { cluebaseFetch } = useCluebaseFetch();

    const handlePay = async () => {
        // Non-ok responses and thrown errors are reported automatically;
        // the response/error is still returned/thrown as normal.
        const res = await cluebaseFetch('https://api.stripe.com/v1/charges', { method: 'POST' });
    };

    return <button onClick={handlePay}>Pay</button>;
}

Isolating a Crash to One Component

By default, a crash anywhere is caught by the app-wide CluebaseProvider boundary and the whole page shows the fallback overlay. Wrap a specific risky section in <CluebaseBoundary> to isolate a crash to just that section (see Isolated Component Recovery for details).

What Gets Captured

When you call reportError(), Cluebase captures:

Error message & stack trace
Current URL and user agent
Session ID for grouping
Timestamp
Your custom context

Avoid sensitive dataDon't include passwords, credit cards, or PII in the error context.

Behavior

Silent: No overlay shown to user
Instant: Sent to API immediately
Full Analysis: AI analysis included