Uniki User Guide

Appearance

11.2 Debugging Workflow ​

Understanding errors is half the battle. The other half is systematically finding and fixing them. This guide provides a proven step-by-step workflow for debugging any error in Taibles.

The Debugging Mindset ​

Approach It Like a Detective ​

Don't panic: Every error has a cause and a solution

Be systematic: Follow steps, don't jump to conclusions

Document findings: Track what you try and what works

Learn patterns: Similar errors often have similar solutions

The 4-Step Debugging Process ​

Step 1: IDENTIFY
↓
Step 2: INSPECT
↓
Step 3: DIAGNOSE & FIX
↓
Step 4: TEST & VERIFY

Let's go through each step in detail.

Step 1: Identify Failed Cells ​

Goal ​

Find all cells that need attention

Visual Scanning ​

Quick scan of taible:

  • Look for cells with "Unsuccessful" badge (blue badge with lightning bolt ⚡)
  • Check column headers for activity indicators
  • Notice patterns (single column? Multiple columns? Specific rows?)

Cell States

⚙️Processing...

Cell is currently running

🕐Queued

Waiting to run

⏸️Rate Limited

Waiting for rate limit to reset

⚡Unsuccessful

Error occurred - click alert button for details

⊘Skipped

Condition not met

⊘Skipped

Dependencies not present

✓john@example.com

Successfully completed

Ready

Not yet run

Method 1: Column Header Activity ​

What to look for:

  • Column header shows green spinning gear ⚙️ (processing)
  • Column header shows amber clock 🕐 with number (queued cells)
  • Hover reveals details about which rows are processing

How to use:

  1. Scan across column headers
  2. Identify columns with activity
  3. Hover over indicators to see tooltips
  4. Click indicators to jump to that cell

Column Activity Indicators

Email ValidationText Column
⚙️

Green spinning gear indicates processing

Company EnrichmentAPI Column
🕐12

Amber clock with count shows queued cells

Benefits:

  • Quick overview of what's happening
  • See which columns are processing or have queued work
  • Navigate directly to active cells

Method 2: Filter by Failed State ​

Show only failed cells:

  1. Click Filter button in toolbar (🔍 icon)

    • Located in top action bar
    • May show a badge with filter count

  2. Filter modal opens

  3. Click "+ Add Filter" button

  4. Configure filter:

    • Field: Leave empty to filter across all columns
    • Operator: Select "Equals"
    • Value: Type FAILED

  5. Click "Save Filters"

  6. Grid now shows only failed rows

Filter Failed Cells

Click the filter button (🔍) to show only failed cells

Result: Focus exclusively on problems

Method 3: Manual Scrolling ​

When to use: Few failures, easy to spot

How:

  1. Scroll through grid
  2. Look for "Unsuccessful" badges (blue with ⚡)
  3. Note row numbers with failures
  4. Click cells to investigate

What to Note ​

As you identify failed cells:

✓ Column names: Which columns are failing?

✓ Row count: How many rows affected?

✓ Pattern: All rows? Specific rows? Random?

✓ Timing: When did failures start?

✓ Scope: Single column or multiple?

Example notes:

- Column: "enrich_contact"
- Affected: 12 out of 50 rows
- Pattern: Random rows (not all)
- Started: Today at 2 PM
- Other columns: Working fine

Step 2: Inspect Error Details ​

Goal ​

Understand what went wrong and why

Viewing Error Information ​

For each failed cell:

  1. Click the failed cell

    • Blue "Unsuccessful" badge with ⚡ icon
    • Cell highlights on click

  2. Hover over the cell

    • Alert button (!) appears in red
    • Button shows on hover

  3. Click alert button

    • Error sidebar slides in from right
    • Shows complete error details

Failed Cell Example

⚡Unsuccessful

Hover to see alert button → Click to view error details

Reading the Error Sidebar ​

Title section (top):

⚠️ API Error
  • Alert icon
  • Short error description
  • Error category

What went wrong section:

The API returned an error: "Invalid API key".
Your credentials may have expired.
  • Friendly explanation
  • What the error means
  • Often includes suggestions

Technical Details section:

Status: 401 Unauthorized
Method: POST
URL: https://api.example.com/v1/enrich
  • HTTP status code and message
  • Request method
  • API endpoint that was called

Response Body:

json
{
  "error": "Invalid API key",
  "code": "auth_failed"
}
  • What the API returned
  • Error codes or messages
  • Scrollable if long

Input Data:

json
{
  "email": "john@example.com",
  "company": "Acme Corp"
}
  • Data from other columns that was used
  • Helps understand context
  • Shows what you sent to the API

Error Details Sidebar

⚠️

API Error

What went wrong:

The API returned an error: "Invalid API key". Your credentials may have expired.

Technical Details:

Status: 401 Unauthorized
Method: POST
URL: https://api.example.com/v1/enrich

Response Body:

{
  "error": "Invalid API key",
  "code": "auth_failed"
}

Input Data:

{
  "email": "john@example.com",
  "company": "Acme Corp"
}

Click the alert button on a failed cell to see this sidebar

Questions to Ask ​

About the error:

  • ❓ What is the error title?
  • ❓ What does the description say?
  • ❓ Is there a specific HTTP status code?
  • ❓ Does it mention missing data or invalid credentials?

About the pattern:

  • ❓ Is it the same error for all failed cells?
  • ❓ Or different errors for different cells?
  • ❓ Is the error message clear or vague?

About the context:

  • ❓ When did this cell last succeed?
  • ❓ Did anything change recently (data, account, settings)?
  • ❓ Are the columns this depends on working?

Copying Error Details ​

For reporting or reference:

  1. Highlight error text in sidebar
  2. Copy (Cmd/Ctrl + C)
  3. Paste into notes or support ticket

Or:

  1. Take screenshot of error sidebar
  2. Include row number and column name

Step 3: Diagnose Root Cause & Fix ​

Goal ​

Determine why error occurred and apply correct fix

Common Error Diagnosis ​

Based on error type (from Section 11.1), follow appropriate fix:

Fix 1: Missing Data Reference ​

Error message: References to column data that doesn't exist

Root cause: Column references non-existent column or cell has no data

Diagnosis steps:

  1. Check error sidebar input data:

    • Does it show the data you expected?
    • Are any fields missing or null?

  2. Verify source columns exist:

    • Look at taible columns
    • Check spelling (case-sensitive!)
    • Ensure column name matches exactly

  3. Check dependencies:

    • Open column settings (click column header ⋯ → Configure column)
    • Go to Run Configuration tab
    • Is the source column in dependencies list?

  4. Check if column has data:

    • Does source column have value (not empty)?
    • Filter to see which rows have empty values

Fix options:

Option A: Add to dependencies

  1. Column settings → Run Configuration tab
  2. Dependencies section
  3. Click "+ Add Dependency"
  4. Select missing column
  5. Save

Option B: Handle missing data

  1. Add condition to skip rows with missing data
  2. Column settings → Conditions tab
  3. Add condition like: Source column is not empty
  4. Save

Option C: Fix source data

  1. Go to source column
  2. Fill in missing values manually
  3. Or add a column before this one to provide default values
  4. Re-run the failing column

Test: Re-run single failed cell to verify fix

Fix 2: Authentication Failed ​

Error message: "401 Unauthorized" or "Invalid API key"

Root cause: API credentials expired, wrong, or revoked

Diagnosis steps:

  1. Check error details: Look at HTTP status (401 = authentication issue)
  2. Check which service: Look at URL in error details
  3. Check account status:
    • Go to Settings (gear icon in top navigation)
    • Click "Accounts" in left sidebar
    • Find the service account
    • Look for warning icons

Fix:

  1. Go to Settings (gear icon in top navigation)

  2. Click "Accounts" in left sidebar

  3. Find the failing service (e.g., "Clearbit Account")

  4. Click "Reconnect" or "Edit"

  5. Complete authorization:

    • For OAuth: Browser opens → Login → Grant permissions
    • For API Key: Enter new API key from service

  6. Test connection:

    • Some accounts have "Test" button
    • Click to verify credentials work

  7. Save account

  8. Return to taible

  9. Re-run failed cells

Prevention: Set calendar reminders to refresh credentials before expiry

Fix 3: Rate Limit Exceeded ​

Error message: "429 Too Many Requests" or "Rate limit exceeded"

Root cause: Too many API calls in short time

Diagnosis steps:

  1. Check error details: Look for rate limit numbers
  2. Check cell state: Cells may show "Rate Limited" with pause icon ⏸️
  3. Count affected rows: How many cells affected?

Fix:

Immediate (let system handle it):

  • Rate limited cells will automatically retry
  • System waits for rate limit to reset
  • Watch cells change from "Rate Limited" → "Queued" → "Processing" → Done

Preventive (configure rate limiting):

  1. Click column header three-dot menu (⋯)

  2. Click "Configure column"

  3. Go to "Run Configuration" tab

  4. Scroll to "Rate Limiting" section

  5. Enable rate limiting:

    • Toggle "Enable" to ON
    • Max requests: Enter limit (e.g., 90)
    • Time window: Enter seconds (e.g., 3600 for 1 hour)
    • Leave buffer below API's actual limit

  6. Save column configuration

See Chapter 8 for complete rate limiting guide

Fix 4: Service Temporarily Down ​

Error message: "500 Internal Server Error" or "Service unavailable"

Root cause: External API temporarily down

Diagnosis steps:

  1. Check error status code: 500, 502, or 503 indicates service issue
  2. Check if all rows failing: If all fail, it's the service, not your data
  3. Check service status: Google "[service name] status" to find their status page

Fix:

Immediate:

  1. Wait for service recovery

    • Check service status page for updates
    • Note estimated recovery time

  2. No changes needed: Your configuration is correct

After service recovers:

  1. Re-run failed cells:

    • Click column header three-dot menu (⋯)
    • Hover over "Re-run"
    • Click "Re-run failed cells"
    • Confirm in dialog

  2. Monitor results:

    • Column header shows spinning gear ⚙️
    • Cells update: Queued → Processing → Done
    • Should succeed now that service is up

Fix 5: Invalid Data Format ​

Error message: "Validation failed" or "Invalid email/phone/format"

Root cause: Data doesn't meet expected format

Diagnosis steps:

  1. Check failed rows: What data do they have?
  2. Look at error sidebar input data: What was sent?
  3. Compare to successful rows: What's different?

Fix:

Option A: Fix data manually

  1. For each failed row:

    • Double-click the source column cell
    • Correct the value (e.g., fix email format)
    • Press Enter to save

  2. Re-run the failing column:

    • Right-click corrected rows
    • Choose "Recalculate range"
    • Select the failing column

Option B: Add validation column

Create a column BEFORE the failing one to validate data:

  1. Add new column (click + next to columns)
  2. Name it: "validate_email" (or similar)
  3. Select type: Custom Code or validation node
  4. Configure to check data format
  5. Add dependency to source data column

Then update the failing column:

  1. Open column settings
  2. Go to Conditions tab
  3. Add condition: Validation column says data is valid
  4. This skips rows with invalid data

Option C: Use enrichment fallbacks

Many enrichment services accept flexible formats. Check service docs.

Fix 6: Timeout Error ​

Error message: "Timeout" or "Request took too long"

Root cause: API response too slow or large data processing

Diagnosis steps:

  1. Check if random: Do retries succeed?
  2. Check data size: Are failed rows processing more data?
  3. Check time of day: Peak hours might be slower

Fix:

Option A: Retry (often succeeds)

  • Timeouts are often temporary
  • Re-run failed cells
  • May succeed on retry

Option B: Reduce data sent

  • If sending large text or many items, reduce size
  • Process in smaller batches
  • Split into multiple columns

Option C: Check API limits

  • Some APIs have size limits
  • Check service documentation
  • Adjust your data accordingly

Fix 7: Missing Dependencies ​

Error message: Cells show "Skipped" with circle-slash icon ⊘

Visual: Gray italic text "Skipped (Dependencies not present)"

Root cause: Column tries to run before required data is ready

Diagnosis steps:

  1. Check dependencies configuration:

    • Column settings → Run Configuration tab
    • What's in dependencies list?

  2. Check dependency column states:

    • Are they done (showing data)?
    • Or are they failed/empty?

  3. Check run mode:

    • Should be "When dependencies change" or "When dependencies exist"

Fix:

If dependencies misconfigured:

  1. Add missing dependencies:
    • Column settings → Run Configuration tab
    • Dependencies section → "+ Add Dependency"
    • Select required columns
    • Save

If dependencies failed:

  1. Fix upstream failures first:
    • Debug dependency columns (follow this same process)
    • Get them to successful state
    • Then this column will automatically run

If execution order wrong:

  1. Run dependencies manually:
    • Click dependency column header ⋯ menu
    • Choose "Re-run" → "Re-run all cells"
    • Wait for them to complete
    • This column will then run automatically

Step 4: Test & Verify Fix ​

Goal ​

Confirm fix works and problem resolved

Test on Single Cell ​

Before mass re-run:

  1. Select one failed row (click checkbox)

  2. Right-click selected row

  3. Choose "Recalculate range" from menu

  4. Select the fixed column

  5. Watch execution:

    • Cell shows clock icon 🕐 (queued)
    • Then spinning gear ⚙️ (processing)
    • Then shows result (done)

  6. Inspect result:

    • Click cell
    • Check data looks correct
    • No "Unsuccessful" badge

If test succeeds: Fix is good, apply to all

If test fails: Error still present, continue diagnosing

Re-run All Failed Cells ​

After confirming fix works:

  1. Click column header three-dot menu (⋯)

  2. Hover over "Re-run" to see submenu

  3. Click "Re-run failed cells"

  4. Confirmation dialog appears

Re-run Confirmation Dialog

Re-run Failed Cells?

All failed cells in this column will be re-tried.

This column has downstream dependencies:

  • lead_score
  • send_notification

These columns may also recalculate.

Do you want to proceed?

Always test on a single cell before re-running all failed cells

  1. Review dialog:

    • Shows what will happen
    • Lists downstream dependencies that may recalculate
    • Asks for confirmation

  2. Click "Recalculate"

  3. Watch progress:

    • Column header shows activity (⚙️ or 🕐)
    • Cells update in real-time
    • Failed cells → Queued → Processing → Done

Monitor Results ​

Watch execution:

Column header updates:

  • Shows spinning gear ⚙️ while processing
  • Shows clock 🕐 with count for queued cells
  • Click to jump to active cell

Visual feedback:

  • Clock icon 🕐 for queued
  • Spinning gear ⚙️ for processing
  • Success: Data appears, no badge
  • Failure: "Unsuccessful" badge remains

Column Header Menu

Column

Click 3-dot menu →

✏️Configure column
↻Re-run
›
↻ Re-run empty cells
↻ Re-run failed cells
↻ Re-run all cells
🧹Clear
›
✏️ Clear cell range
🧹 Clear column
🗑️Delete column

Use "Re-run failed cells" to retry all failed cells in this column

Expected outcome:

  • All or most cells complete successfully
  • Few or no "Unsuccessful" badges
  • Problem resolved

If Problems Persist ​

Some cells still failing:

  1. Check if same error:

    • Click failed cell
    • Click alert button
    • View error details
    • Same error or different?

  2. If same error:

    • Fix didn't work completely
    • Go back to Step 3
    • Try different solution or adjust current fix

  3. If different error:

    • New problem revealed
    • Start debugging workflow for new error

  4. If specific rows fail:

    • Data quality issue for those rows
    • Fix data manually
    • Or add validation to handle edge cases

Advanced Debugging Techniques ​

Technique 1: Clear and Start Fresh ​

When to use: Configuration changes that might cause conflicts

How:

  1. Click column header three-dot menu (⋯)

  2. Hover over "Clear" to see submenu

  3. Choose "Clear column" or "Clear cell range"

  4. For range: Enter row numbers in modal

  5. Confirmation dialog appears

  6. Click "Clear"

  7. All cells show "Ready" (gray, italic)

  8. Re-run column:

    • Column menu ⋯ → Re-run → Re-run all cells

Benefit: Ensures clean execution with new configuration

Technique 2: Test with Sample Rows ​

When to use: Major configuration changes

How:

  1. Add filter to show 5-10 sample rows:

    • Mix of different scenarios
    • Representative data

  2. Run column on sample only:

    • Select sample rows (checkboxes)
    • Right-click → Recalculate range
    • Choose column

  3. Verify results for all samples

  4. If successful:

    • Remove filter (show all rows)
    • Run on remaining rows

Benefit: Catches issues early without processing all rows

Technique 3: Dependency Chain Analysis ​

When to use: Complex multi-column dependencies

How:

  1. Identify dependency chain:
email (manual entry)
  ↓
validate_email (validation)
  ↓
enrich_contact (API enrichment)
  ↓
score_lead (AI analysis)

  1. Test each level:

    • Level 1: Check "email" has data
    • Level 2: Run "validate_email", verify works
    • Level 3: Run "enrich_contact", verify works
    • Level 4: Run "score_lead", verify works

  2. Find where chain breaks

  3. Fix that level

  4. Continue down chain

Benefit: Isolates exact point of failure in complex workflows

Technique 4: Comparison Analysis ​

When to use: Some rows succeed, others fail

How:

  1. Select one successful row

  2. Note data values in all columns

  3. Select one failed row

  4. Compare data values side by side

  5. Identify difference:

    • Different data format?
    • Null where successful has value?
    • Special characters?
    • Number out of range?

  6. Pattern emerges:

    • All failures have X in common
    • All successes have Y in common

  7. Fix data or add handling for pattern

Benefit: Reveals data quality patterns

Debugging Checklist ​

Use this checklist for any error:

☐ Step 1: Identify ​

  • [ ] Found all failed cells (look for "Unsuccessful" badges)
  • [ ] Noted pattern (all rows? some rows? random?)
  • [ ] Checked column headers for activity
  • [ ] Filtered to show only failed cells (optional)

☐ Step 2: Inspect ​

  • [ ] Clicked failed cell(s)
  • [ ] Hovered to see alert button
  • [ ] Clicked alert button to open error sidebar
  • [ ] Read what went wrong
  • [ ] Noted technical details (status code, URL)
  • [ ] Checked input data that was used
  • [ ] Copied error details (if needed)

☐ Step 3: Diagnose & Fix ​

  • [ ] Identified root cause from error message
  • [ ] Selected appropriate fix (auth, data, rate limit, etc.)
  • [ ] Applied fix (reconnect account, fix data, add validation, etc.)
  • [ ] Documented what was changed

☐ Step 4: Test & Verify ​

  • [ ] Tested on single cell first
  • [ ] Verified fix works
  • [ ] Re-ran all failed cells
  • [ ] Monitored results
  • [ ] Confirmed problem resolved
  • [ ] Documented solution for future reference

Common Pitfalls to Avoid ​

❌ Pitfall 1: Fixing Symptoms, Not Root Cause ​

Wrong approach:

Error: Missing data reference
Fix: Remove that part of the workflow
Result: Column runs but produces wrong output

Right approach:

Error: Missing data reference
Investigate: Why is data missing?
Fix: Add source column to dependencies
Result: Column runs correctly with proper data

❌ Pitfall 2: Mass Re-run Without Testing ​

Wrong approach:

1. See 1000 failed cells
2. Change configuration
3. Re-run all 1000 immediately
4. All fail again (wrong fix)
5. Waste time and API credits

Right approach:

1. See 1000 failed cells
2. Change configuration
3. Test on 1 cell
4. Verify fix works
5. Then re-run all

❌ Pitfall 3: Ignoring Error Messages ​

Wrong approach:

Error: "Invalid API key"
Fix attempted: Change data format
Result: Still fails (didn't address actual issue)

Right approach:

Error: "Invalid API key"
Fix: Reconnect account with valid credentials
Result: Fixed

Tip: Error messages usually tell you exactly what's wrong. Read them carefully!

❌ Pitfall 4: Not Documenting Fixes ​

Wrong approach:

- Fix error somehow
- Forget what you did
- Same error next month
- Waste time debugging again

Right approach:

- Fix error
- Document in notes:
  "Error: Rate limit on Clearbit API
   Fix: Added rate limit 90/hour
   Date: 2024-10-31"
- Next time: Refer to notes

Summary: Debugging Workflow ​

You now have a systematic debugging approach:

✅ 4-Step Process:

  1. Identify failed cells (scan, filter, check headers)
  2. Inspect error details (click cell, view error sidebar)
  3. Diagnose & fix (match error to solution)
  4. Test & verify (single cell → all cells)

✅ Common fixes:

  • Missing data → Add dependencies or handle empty values
  • Auth errors → Reconnect accounts
  • Rate limits → Configure rate limiting (see Chapter 8)
  • Service down → Wait and retry
  • Data validation → Fix data or add validation column
  • Timeouts → Retry or optimize data size
  • Dependencies → Fix upstream columns or add to config

✅ Advanced techniques:

  • Clear and start fresh
  • Test with sample rows
  • Dependency chain analysis
  • Comparison analysis (compare successful vs failed rows)

✅ Best practices:

  • Test fixes on single cell first
  • Read error messages carefully
  • Fix root cause, not symptoms
  • Document solutions
  • Use checklists

✅ Tools available:

  • Column menu re-run options
  • Filter button to show only failures
  • Error sidebar with complete details
  • Right-click context menus for quick actions

Next Steps ​

Now that you can debug errors, Section 11.3 will cover:

  • Advanced debugging tools
  • Viewing execution history
  • Understanding cell state transitions
  • Performance troubleshooting
  • Testing configurations before deployment

Let's master the debugging toolkit!

Built with VitePress

Copyright © 2025 Uniki