Troubleshooting Common StretchSearch Errors

This article collects the errors and surprises you're most likely to hit in StretchSearch and how to resolve each. Most fall into four buckets: validation errors, not-found errors, governance blocks, and empty results.

Validation errors

A VALIDATION_ERROR (or a message like "Invalid StretchSearch … payload") means a field didn't pass the rules. The most common causes:

1. Projects — the name is required and capped at 180 characters; type must be one of the allowed values (owned_site, client_site, competitor_research, brand_audit, seo_intelligence, research).
2. Targets — the root URL must be a valid https:// URL and the domain must be non-empty. Allowed prefixes must also be valid URLs. You can list at most 50 allowed domains and 100 prefixes.
3. Crawl jobs — you need at least one valid seed URL (up to 250). Limits must be in range: max_depth 0–10, max_pages 1–5,000, rate_limit_ms 250–60,000.
4. Saved searches — a non-empty query is required before you can save.

Fix: read the field the message points to, correct the value into range, and resubmit.

Not-found errors

Messages like "StretchSearch project/target/crawl job was not found" (HTTP 404) usually mean one of:

• You referenced an item from a different project or a different organization. Everything is org- and project-scoped.
• The item was archived and you're looking at the active view.
• You used an id or key that doesn't exist (typo, or an item deleted/cancelled).

Fix: confirm you're in the right project and organization, include archived items in the view if needed, and re-copy the id/key.

Governance blocks

If a crawl job won't run or won't advance:

1. Readiness not met — required checklist items aren't passed/not_applicable, or an item is blocked. Work the readiness checklist.
2. Not approved — governance status hasn't reached approved. Set it to review_required and get sign-off (recorded in approved_by).
3. Execution disabled — the default. crawler_enabled: false is expected until a platform operator enables execution for the approved job.
4. Kill switch engaged — a global halt overrides everything. Check its status.
5. Authorization blocked — a target or job marked blocked will not run by design.

"I don't need admin rights" but an action is refused

Workspace users can manage projects, targets, crawl jobs, readiness items, and searches, and review findings, rankings, evidence, and retrieval. Governed generation and controls are operator-only: generating SEO findings, generating ranking previews, and toggling the kill switch require scoped action tokens. If one of those is refused for you, route it to a platform operator.

Empty results

• No SEO findings — pages may be clean, or findings haven't been generated for the scope yet. Confirm pages are indexed, then have an operator generate findings.
• No candidates/ranking previews — these derive from indexed pages. If nothing is indexed for the scope, the views are empty.
• No federated results — check your filters. The apps filter only accepts stretchsearch, stretchprojects, stretchcrawler, and stretchseo; other values are ignored. Also confirm the project/status filters aren't over-narrowing.
• Stale results — federated freshness decays over ~90 days; recently updated items rank higher.

A realistic example

An analyst can't get a crawl job past needs_review. They open the readiness checklist and find a required "Written authorization on file" item still pending. They mark it passed with the permission reference in notes; readiness flips to ready. Governance is still draft, so they set review_required, the lead approves, and the operator enables execution. The job now runs.

Tips

• When you see a validation error, the field name in the message is the fastest path to the fix.
• Keep an eye on crawler_enabled: false — it's informational, not a bug.
• If something "disappeared," check whether it was archived before assuming it was deleted.
• For anything governed (generation, kill switch), confirm whether it needs an operator before troubleshooting further.

FAQ

Why does every crawl response say no execution was started? Because StretchSearch is governance-first. Creating and editing records never starts a crawl; execution is enabled centrally after approval.

I fixed a page but the finding is still open. Findings reflect the last generation. Re-generate to supersede the stale open finding.

A saved search won't save. You must have a non-empty query. Enter a query, apply filters, then save.