Core Features / Repair Broken Selectors

Repair Broken Selectors

ScraperQ's Selector Repair Engine (CSRE) automatically fixes broken templates when websites update their layout.

How CSRE Works

The Selector Repair Engine uses a multi-stage approach to fix broken selectors.

When a website changes its HTML structure, the CSS selectors in your template may break. CSRE handles this automatically:

1

Detection

CSRE monitors health signals for every selector during scraping. When a selector fails to match elements, it's flagged as broken.

2

Hierarchical Repair

CSRE tries multiple repair strategies in order: stable attributes → semantic matching → AI-powered fix.

3

Approval & Auto-Fix

When a repair is found, ScraperQ shows you the proposed fix. After approval, the template is updated and your next run works.

Repair Strategies

CSRE uses multiple strategies to find the best replacement selector.

1. Stable Attributes

First, CSRE looks for stable HTML attributes that are unlikely to change:

  • data-testid — test identifiers
  • aria-label — accessibility labels
  • id — unique IDs (if stable)
  • name — form element names

2. Semantic Matching

If stable attributes aren't available, CSRE analyzes the semantic structure:

  • Element hierarchy and nesting patterns
  • Text content similarity
  • Position within parent containers
  • Adjacent element relationships

3. AI-Powered Fix

As a last resort, CSRE uses AI to analyze the page and suggest a new selector:

  • Analyzes the original field description
  • Searches for similar content on the updated page
  • Generates a new CSS selector that targets the same data

Credit Cost

AI-powered repairs consume credits: 10 credits + 1 credit per field repaired. You'll be notified before any credits are deducted.

Repair Workflow

Step-by-step guide to repairing broken selectors.

1

Broken Selector Detected

When you run a template and a selector fails, ScraperQ displays a notification with the broken field(s).

Broken selector alert

Replace with actual extension screenshot

ScraperQ detects a broken selector
2

Review Repair Suggestions

CSRE analyzes the page and presents repair options. For each broken selector, you'll see:

  • The original selector
  • The proposed replacement selector
  • Preview of what the new selector matches
  • Confidence score for the repair

Repair suggestions panel

Replace with actual extension screenshot

Review proposed selector repairs
3

Approve or Reject

For each suggested repair:

  • Approve — accept the new selector and update the template
  • Reject — skip this repair and manually edit if needed
  • Edit — modify the selector yourself before approving
4

Template Updated

After approval, your template is updated. The next time you run it, the new selectors will work correctly.

Automatic Future Repairs

Once repaired, CSRE continues monitoring the selectors. If the same field breaks again in the future, ScraperQ will automatically apply the repair without requiring your approval (if you enable auto-repair).

Manual Selector Editing

For advanced users who want full control over selectors.

You can always manually edit selectors if the AI suggestion doesn't work:

1

Enter Edit Mode

In the template editor, click on any field to open the selector editor.

2

Use Selector Picker

Click on any element on the page to auto-generate a CSS selector. Or type your own selector in the input field.

Selector Tips

  • Use .class-name for class selectors
  • Use #element-id for ID selectors
  • Use div > p for child selectors
  • Use [data-testid="value"] for attribute selectors
3

Test Selector

Click "Test" to verify the selector matches the correct elements on the page.

Test Case: Repairing a Product Template

A practical example of the repair workflow.

Scenario: E-commerce Site Updates Product Cards

  1. Run your "Product Listing" template
  2. ScraperQ detects: "product-title" selector returns 0 results
  3. CSRE analyzes the updated page structure
  4. CSRE finds: new class name is "product-card__title"
  5. ScraperQ shows repair suggestion with confidence: 95%
  6. You approve the repair
  7. Template is updated, next run works correctly

Expected Result: Template successfully repaired, data extraction resumes with correct product titles.

← Running Templates Export Options →