Appearance
Troubleshooting
A consolidated index of every "something looks wrong, what now" path. The matrices in installation / setup-menu / support also live here so you can search one page instead of three.
Start here: open
/setup→ ℹ️ About in your group. The four lines on that screen (chat ID, plan, schedule, project name) are what support needs to triage. Copy them before you do anything else.
Self-diagnosis flow
Run through these questions in order. Most issues resolve at one of the first two checks.
1. Does the bot reply to /setup at all?
├─ No → bot was kicked or demoted from admin → re-promote and retry
└─ Yes → continue.
2. Does /setup → 📊 Reports → ⚡ Generate report now produce a post
within 3 minutes?
├─ No DM, no post → check matrix in §"Reports not arriving"
├─ DM "no posts found" → see §"Filter / no posts"
├─ DM "credit exhausted" → see §"Billing & credits"
├─ Post landed but renders wrong → see §"Render quality"
└─ Post landed correctly → you're fine.
3. Are scheduled reports arriving on time?
├─ No → see §"Schedule not firing"
└─ Yes → all good.
4. X Posts Auto-relay issues?
└─ See §"X Posts Auto-relay"If none of the matrices below land you on a fix, scroll to Escalation.
Reports not arriving
| Symptom | Likely cause | Fix |
|---|---|---|
| Bot was active before, suddenly silent | Bot was demoted from admin / kicked silently | Telegram → group admins → re-promote. If still silent, contact support — the auto-disable on chat-gone may have triggered. |
| Manual generate-now produces nothing | Bot is admin but has zero credits | /setup → 💳 Buy Credits. If FREE "100/100 used" — wait for monthly reset (1st of month UTC). If PRO·credits with REMAINING=0 — chat already auto-downgraded to FREE; /setup → 💳 → 💰 Buy to top up. |
| Manual generate-now: "no posts found" admin DM | Filter too narrow OR no posts in window | /setup → 🎯 Filters. Check the literal X API query for typos. Try widening or dropping the period. |
| Image renders but text empty | AI commentary timed out | Re-run; transient. Persistent = contact support. |
| Image fails to render entirely | Transient rendering hiccup | Re-run. If repeatedly failing for one chat, contact support with chat ID. |
| Error "Unauthorized" / "Forbidden" in admin DM | X API token issue (operator-side) | Contact support; nothing the user can fix. |
Filter / no posts
| Symptom | Likely cause | Fix |
|---|---|---|
| Report shows "0 posts" everywhere | Filter doesn't match anything in the configured period | Step 1: /setup → 🎯 Filters — confirm the query. Step 2: /setup → 📊 Reports → 🗑 Clear period (rolling 24h is more forgiving). Step 3: widen filters (add a cashtag fallback, drop strict keyword groups). |
| Leaderboard shows users I didn't add to the filter | Filters are additive — anyone tweeting a tracked cashtag/keyword counts | To require both an account and a cashtag, use /set_x_filtering name from:@x cashtags:$Y (named filter, AND-of-categories). |
| Same user spammed leaderboard | Bot legitimately scored every post | /setup → 🎯 Filters → 🙈 Ignore → ➕ Add @spammer — they're dropped from results post-fetch. |
| Cashtag with weird characters not matching | X API normalizes case; trailing/leading spaces matter in filter input | Re-add via /setup → 🎯 Filters → 💵 Cashtags → ➕ Add → no $ needed, no spaces. |
Number-prefixed cashtag (e.g. $1INCH) isn't tracked | X API search behavior with leading numbers can be inconsistent | Use as a keyword instead of a cashtag: "$1INCH" in 🔍 Keywords with quotes. |
| "Best Tweet" pick seems off | AI deduplication recently picked a similar tweet | Wait one cycle. Persistent off-feel = report it; the prompt is tunable. |
Schedule not firing
| Symptom | Likely cause | Fix |
|---|---|---|
Schedule "rejected" with FREQUENCY_ERROR | Cron tries to fire more often than every 12h | Spacing check enforces ≥ 12h gaps. The error message names the offending hour pair. Pick a wider gap. |
| Schedule set, but report didn't arrive on time | Scheduled cron fires within ~1–2 min of the tick | Wait 5 min after the configured time before assuming a miss. Rare upstream delays happen but resolve themselves. |
| Multi-fire cron only fires once | Hour list out of order or duplicate | cron(0 14,22 ? * * *) — ascending hours. cron(0 22,14 ? * * *) is rejected. |
| Schedule on staging fires every 5 min, prod doesn't | Different RULE_NAME namespace | Confirm you're checking the right environment. /setup → ℹ️ About shows env. |
| Time zone seems wrong | Schedule is UTC by design | Convert your local time to UTC. The set-schedule input also accepts named timezones in some edge cases — check the entry's docstring. |
| X Posts Auto-relay fires but reports don't | Different cron schedules | X Posts Auto-relay uses a 5-min poll per relay; reports use the chat's main schedule cron (typically daily). They're independent. |
Render quality
| Symptom | Likely cause | Fix |
|---|---|---|
| Custom title / color reverted overnight | Cache invalidated, next fetch shows the new value | Wait one report cycle (~1 day). The render cache rebuilds on the next fetch. |
| Logo blurry / cropped | Source image too small or non-square | Re-upload at ≥ 512×512 PNG, square aspect. /setup → 🎨 Customization → 🖼 Logo. |
| Username overflows in the leaderboard image | Long display name | Bot truncates with ellipsis; no fix needed unless persistent. |
Best-tweet text shows raw <a href> HTML | Telegram parse mode mismatch | Bug — please report with the tweet URL. |
| Different report image vs Telegram preview | Telegram caches the first image bytes by URL; presigned URLs include a timestamp so each fetch is unique | Should not happen; if it does, rotate via /recreate. |
X Posts Auto-relay
| Symptom | Likely cause | Fix |
|---|---|---|
| Relay forwards a 6-tweet thread at once | Self-replies bypass X API's exclude=replies | /setup → 📡 X Posts Auto-relay → @account → toggle ☐ Thread continuations off. Bot then keeps only the head. |
| Relay stopped mid-day | Daily cap reached | Per-relay screen shows Today: N/N forwarded. Tap ✏️ Cap and raise. Resets at midnight UTC. |
| Relay shows ⏸ Paused but I never paused it | Auto-paused on Telegram chat-gone (kicked / blocked / chat upgraded) | The bot also stopped the polling schedule. To restore: /setup → 📡 X Posts Auto-relay → @account → ▶️ Resume. If still failing, the chat itself may have changed ID (super-group upgrade) — re-add the bot in the new chat. |
| Relay's first poll forwarded 50 posts | Bootstrap shouldn't do this — only seed the LAST_POST_ID without forwarding | If you see this, please report. The fix added in 2026-04 should prevent it. |
| Quote tweets keep appearing despite the toggle | X API has no server-side exclude=quotes — bot filters client-side post-fetch | Toggle works, but you still pay for the quote tweets returned by the API. Cosmetic-only saving. |
| Relay polls forever despite chat being deleted | Old-version relay — auto-cleanup added 2026-05 | Ask support to force-stop the relay. New deployments self-clean. |
Billing & credits
| Symptom | Likely cause | Fix |
|---|---|---|
| Bought credits, balance unchanged | Stripe webhook delayed | Wait 5 min. If still wrong, contact support with Stripe receipt + chat ID. |
| Credit count higher than I expected | A relay polled multiple times during a period when the tracked account was active | X Posts Auto-relay charges per post. Tap relay → check Today counter. |
| Overage charge on PRO·sub even though I posted little | Other usage on the chat (relays, reports, fetch retries) | /setup → 💳 Buy Credits → Usage this month. Compare against the metered charge. |
| FREE chat charged | Shouldn't happen — FREE has no Stripe customer | Report immediately; this is a billing bug. |
| Subscription shows "canceled" but I didn't cancel | Stripe cancellation can be triggered by failed card auto-renew | Check email for Stripe receipts, update card via /setup → 💳 → 🛠 Manage subscription (Stripe Customer Portal). |
| Cancelled subscription, still PRO | Cancel-at-period-end: PRO until end of paid period | Expected. Reverts to FREE at the next billing cycle's end. |
Public dashboard
| Symptom | Likely cause | Fix |
|---|---|---|
| Project not on xbot.ninja | Doesn't meet thresholds (≥ 300 top score, ≥ 5 posts, ≥ 2 active users this month) | Direct URL still works. Wait for the metric to reach the threshold. Solo-KOL setups are intentionally hidden from the showcase. |
| Project on xbot.ninja but logo missing | Logo never uploaded, or upload failed | /setup → 🎨 Customization → 🖼 Logo. Send a square PNG. |
| Public URL shows old project name | Refresh on next report cycle | Rename via /setup → 🎨 Customization → 🏷 Name. URL slug + card refresh once the next report fires. |
| URL gives 404 | Chat has been hard-deleted, OR thresholds not met yet so showcase hides it | Confirm chat ID via /setup → ℹ️ About. Test the direct URL https://xbot.ninja/?chatId=<id>. |
Escalation
When matrices above don't resolve, contact support with the template below.
Project: <your project name>
Chat ID: <from /setup → ℹ️ About>
Plan: FREE / PRO·credits / PRO·sub
What's wrong: <1–2 sentences>
What you tried: </setup → … → … steps you ran>
When it broke: <approx UTC time>
Recent change: <any new filter / schedule / payment in the last 24 h>The chat ID alone gives support 80% of triage information — please always include it.
Where to send:
- General support: bws.ninja contact form
- GitHub issues (open-source aware): bws-api-telegram-xbot/issues
- Direct Telegram: @BlockchainWebServices
Response times by severity:
- Critical (bot offline platform-wide, billing failures): 1 business hour during EU+US business overlap
- High (one chat's report not delivering): same business day
- Normal (feature questions, configuration help): 1–2 business days
Useful diagnostics commands
| Command | What it shows |
|---|---|
/setup → ℹ️ About | Chat ID, plan, schedule, project — copy this verbatim into support |
/setup → 🎯 Filters | Literal X API query string |
/setup → 💳 Buy Credits → 📊 Usage this month | Daily + monthly fetched_posts counters — spots silent failures (high attempts, zero posts → likely 402s) |
/setup → 📡 X Posts Auto-relay → @account | Per-relay state (active / paused, today's forwards, daily cap) |
/get_chatid | Just the chat ID (one-liner if About is overkill) |
Where to go next
- Installation — clean re-install if everything else fails
- The /setup menu — full menu reference
- Pricing — billing-side troubleshooting
- Support — FAQ + contact escalation