Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
228 lines (173 loc) · 8.15 KB

TROUBLESHOOTING.md

File metadata and controls

228 lines (173 loc) · 8.15 KB
Raw

xoperator Troubleshooting Guide

Common pitfalls and solutions for xoperator setup and operations.

⚠️ Pitfall 1: Incomplete Data Collection - Executed Only 1 Query and Thought It Was Done

Wrong Understanding:

  • "I executed TWITTER_RECENT_SEARCH once, saved as rube-slice-1.json, should be done"
  • "I see LONG_LIST.md was generated, so I did it right"

Correct Understanding:

  • Need to execute 10 queries (not 1!), each FETCH_ARGS-N.json corresponds to one query
  • Even with only 1 file, xop-hotspot-refresh.py will run, but candidate quality will be extremely poor
  • LONG_LIST.md has content ≠ correct operation (might only have 1 candidate, all from same author)

How to Avoid:

  1. Verify file count: ls work/hotspot/rube-slice-*.json | wc -l must output 10
  2. Check logs: refresh log's tweet_count should be ~100 (not 1-10)
  3. Check diversity: LONG_LIST.md candidates should come from different authors (not all same person)
  4. Tool protection: From now on, xop-hotspot-refresh.py will automatically check completeness, refusing to continue if less than 10 files

Correct FETCH_ARGS and rube-slice correspondence:

FETCH_ARGS-1.json  → Query 1 → Save as rube-slice-1.json
FETCH_ARGS-2.json  → Query 2 → Save as rube-slice-2.json
FETCH_ARGS-3.json  → Query 3 → Save as rube-slice-3.json
...
FETCH_ARGS-10.json → Query 10 → Save as rube-slice-10.json

NOT:

  • ❌ Execute one query, system automatically generates 10 files (won't auto-generate)
  • ❌ Save as rube-slice.json (singular), system auto-splits (won't auto-split)
  • ❌ Do 1 query, then expect tools to "fill remaining data" (tools won't fill data)

⚠️ Pitfall 2: Thought Data Collection Succeeded Because LONG_LIST.md Generated Successfully

Wrong Signal Judgment:

  • "refresh ran successfully" → ✅ Only means tool ran, doesn't mean data quality is good
  • "LONG_LIST.md has content" → ✅ Only means there's data, doesn't mean data is sufficient

Correct Verification Method:

  1. Check tweet_count in logs:
    • Should be about 100 tweets (10 queries × ~10 tweets each)
    • If only 1-10 tweets → means only executed 1 query
  2. Check candidate diversity:
    • LONG_LIST.md should have 2-5 candidates
    • From different authors (not all @same_person)
  3. Check completeness prompt:
    • refresh will output: ✅ 数据完整性检查通过: 10/10 个slice文件
    • If you see: ⚠️ 数据采集不完整！... 2/10 (20%) → means you missed some

⚠️ Pitfall 3: Thought "FETCH_ARGS" and "rube-slice" Would Auto-Correspond

Common Confusion:

  • "I see 10 FETCH_ARGS, but docs say 'save as rube-slice-*.json', what does * mean?"
  • "Do I just execute once and system will auto-process 10 files?"
  • "rube-slice-1.json is already generated, are the other 9 auto-generated?"

Clear Answer:

  • * is a wildcard, meaning rube-slice-1.json, rube-slice-2.json, ..., rube-slice-10.json
  • Won't auto-generate, each file needs manual (or agent manual) execution of one RUBE query
  • If you only have rube-slice-1.json, it means you only did 1/10 of the work

⚠️ Pitfall 4: Don't Know How to Judge "I Did It Right"

Peer's Most Common Mental Path (Wrong):

  1. Executed query → ✅
  2. Saved file → ✅
  3. refresh ran successfully → ✅
  4. Thought it was done ❌

Correct Completion Checklist:

  • ls work/hotspot/FETCH_ARGS-*.json | wc -l outputs 10
  • ls work/hotspot/rube-slice-*.json | wc -l outputs 10 (same count as FETCH_ARGS)
  • python3 tools/xop-hotspot-refresh.py run shows ✅ 数据完整性检查通过: 10/10
  • LONG_LIST.md has 2-5 candidates from different authors
  • refresh log shows tweet_count: ~100 (not single digits)

If any item is not satisfied → Go back and check, complete missing queries

⚠️ Pitfall 5: Used Wrong RUBE MCP Tool - Data Format Completely Mismatched

Wrong Operation:

  • Saw "query" field in FETCH_ARGS
  • Selected web search tool in RUBE MCP (like mcp__web-search-prime__webSearchPrime)
  • Or used other non-Twitter API search tools
  • Saved web search results to rube-slice-N.json

Why This Mistake Happens:

  • The query parameter in FETCH_ARGS looks like "generic search query"
  • RUBE has multiple tools that can "search", easy to pick wrong one
  • Don't understand that parameters in FETCH_ARGS (expansions, tweet_fields, user_fields) are Twitter API specific

Actual Consequences:

# Web search returns this format (WRONG!)
{
  "results": {
    "organic_results": [
      {"title": "...", "link": "...", "snippet": "..."}
    ],
    "search_information": {...}
  }
}

# Twitter API returns this format (CORRECT)
{
  "data": [
    {"id": "...", "text": "...", "author_id": "...", "public_metrics": {...}}
  ],
  "includes": {
    "users": [{"id": "...", "username": "...", "public_metrics": {...}}]
  },
  "meta": {"result_count": ...}
}

How Tools Detect This:

$ python3 tools/xop-hotspot-refresh.py run

[WARNING] 文件rube-slice-5.json不包含有效的Twitter API响应结构，已跳过
[WARNING] 文件rube-slice-6.json不包含有效的Twitter API响应结构，已跳过
...
[xop-hotspot-refresh] DISCOVERED 2 slice(s): ['rube-slice-1.json', 'rube-slice-2.json']

⚠️  数据采集不完整！
发现 10 个查询计划（FETCH_ARGS-*.json）
但只找到 2 个数据文件（rube-slice-*.json）

Correct Operation:

  1. In RUBE MCP, must select TWITTER_RECENT_SEARCH tool

    • Not web search
    • Not generic search
    • Only TWITTER_RECENT_SEARCH can return correct Twitter API v2 format

  2. Parameters in FETCH_ARGS are Twitter API specific:

    • query: Twitter search syntax (like from:username, lang:en, -is:retweet)
    • expansions: Twitter API field expansion parameters
    • tweet_fields: Tweet field selection
    • user_fields: User field selection
    • These parameters only TWITTER_RECENT_SEARCH understands

How to Verify:

# Verification 1: Check file format
head -1 work/hotspot/rube-slice-1.json

# ✅ Correct: should see
{"data":[...

# ❌ Wrong: if you see
{"results":{...
# → means wrong tool used, this is web search result

# Verification 2: Check key fields
jq 'keys' work/hotspot/rube-slice-1.json

# ✅ Correct: should see
["data", "includes", "meta"]

# ❌ Wrong: if you see
["results"]
# → means wrong tool used

How to Fix:

  1. Delete files with wrong format:

    rm work/hotspot/rube-slice-5.json  # or other wrong files

  2. Re-execute query (using correct tool):

    • In RUBE MCP, select TWITTER_RECENT_SEARCH
    • Read FETCH_ARGS-5.json, copy content
    • Paste into TWITTER_RECENT_SEARCH parameter input
    • Execute, save complete response to rube-slice-5.json

FETCH_PLAN now clearly states:

  • From now on, generated FETCH_PLAN-*.md will clearly mark "must use TWITTER_RECENT_SEARCH tool"
  • Will list common errors and verification methods
  • Please carefully read the "Execution Tips" section in FETCH_PLAN

💡 Remember: Tools Will Now Check for You

From now on, xop-hotspot-refresh.py will automatically check before merging:

  • ✅ Found 10 FETCH_ARGS but only 2 rube-slice → Error and refuse to continue
  • ✅ Clearly tell you which files are missing (like rube-slice-3.json, rube-slice-4.json ...)
  • ✅ Provide operation step guidance
  • ⚠️ Unless you add --force-incomplete (not recommended), won't allow continuation

This check is to protect data quality and prevent low-quality candidates from entering the pipeline.

Additional Troubleshooting

RUBE MCP Connection Issues

  1. Verify rube.app account is active and X account is connected
  2. Check RUBE MCP is properly configured in your CLI
  3. Run python3 tools/xop-preflight.py --diagnose for connection status

"Sample Too Cold" Warnings

This means current Influencer pool tweets don't meet quality thresholds. This is normal — wait for next refresh cycle rather than lowering thresholds.

Candidate Validation Errors

Run python3 tools/xop-lint.py to identify specific validation failures.

For general setup guidance, see README.md and CUSTOMIZATION.md.