Troubleshooting

Troubleshooting

Common issues and their fixes, organized by integration.

---

Telegram

Rate limiting on list_dialogs

Symptom: Telegram MCP returns a FLOOD_WAIT_X error, or dialogs stop loading mid-request. Skills that use Telegram (e.g., /ops:inbox telegram) silently return fewer results or fail.

Cause: Telegram's MTProto API enforces rate limits on getDialogs calls. The 8-hour cooldown is standard after rapid consecutive calls.

Fix:

• Wait for the cooldown to expire (up to 8 hours for aggressive rate-limiting)
• Use search_messages instead of list_dialogs for targeted lookups — it hits a different endpoint
• Reduce frequency: avoid calling /ops:inbox telegram more than once per hour

Prevention: The bundled Telegram MCP server (telegram-server/) handles this gracefully — it returns partial results rather than failing hard. If you see truncated dialog lists, this is the rate limiter.

---

Session string expired

Symptom: Telegram MCP logs AUTH_KEY_INVALID or SESSION_REVOKED. All Telegram tools return auth errors.

Cause: The gram.js session string stored in plugin settings was revoked — either because you logged out of Telegram on another device, or Telegram invalidated old sessions.

Fix: Re-run the Telegram setup to generate a new session:

/ops:setup telegram

This runs bin/ops-telegram-autolink.mjs, which generates a fresh session string. Paste the new value into /plugin settings for ops@ops-marketplace → telegram_session.

---

WhatsApp

App-state key desync

Symptom: wacli connects but messages fail to send/receive, or contacts show as "unknown". wacli doctor shows CONNECTED: true but AUTH_STATE: degraded.

Cause: WhatsApp Web protocol requires periodic app-state key syncs. After extended inactivity (typically 2–4 weeks), the local key store goes out of sync with WhatsApp servers.

Fix:

wacli auth logout
wacli auth login   # Re-scan QR code from your phone

After re-pairing, run wacli doctor to confirm AUTHENTICATED: true and CONNECTED: true.

Prevention: Keep at least one wacli session active every 2 weeks. The setup wizard runs wacli doctor automatically and will flag desync.

---

wacli command not found

Symptom: Skills that use WhatsApp report wacli not available. /ops:setup shows ○ wacli (not installed).

Cause: wacli is not on Homebrew and requires a manual install.

Fix: See the wacli repository for install instructions. After installing:

/ops:setup cli   # re-run CLI detection to update status

---

Slack

Token expiry

Symptom: Slack MCP returns invalid_auth or token_revoked. /ops:inbox slack fails silently or returns no results.

Cause: Slack OAuth tokens can expire or be revoked when:

• The user revokes app access in Slack settings
• The Slack workspace admin revokes the integration
• The Claude.ai MCP connection needs re-authorization

Fix:

/ops:setup mcp   # re-run MCP setup and re-authorize Slack OAuth

If using the local bot token path: re-run bin/ops-slack-autolink.mjs to extract fresh tokens from the browser session.

---

MCP quota exhaustion

Symptom: Slack MCP search returns ratelimited or stops returning results after several queries in a session.

Cause: The Claude.ai Slack MCP has per-session quota limits on search calls.

Fix — use local token for unlimited search:

/ops:setup channels   # set up local Slack bot token

The local token path bypasses the MCP quota entirely. It also gives access to private channels without requiring the bot to be a member.

Temporary workaround: Space out search calls. /ops:inbox slack batches searches to minimize quota usage.

---

MCP general — quota exhaustion and fallback

Symptom: Any MCP tool (Sentry, Linear, Slack) returns quota or rate limit errors mid-session.

General pattern:

• Sentry MCP: fall back to sentry-cli issues list --project <slug> or direct API via curl -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" https://sentry.io/api/0/projects/<org>/<project>/issues/
• Linear MCP: fall back to curl -X POST https://api.linear.app/graphql -H "Authorization: $LINEAR_API_KEY" -d '{"query":"..."}'
• Slack MCP: fall back to local bot token if configured

Skills handle this gracefully — when a MCP tool fails, they check for CLI alternatives before surfacing an error.

---

SessionStart hook warnings

Symptom: Claude Code shows a warning at session start about a hook command failing. The warning message starts with ✗.

Cause: The plugin installs a SessionStart hook (hooks/hooks.json) that runs scripts/setup.sh to detect missing configuration. If any required item is not set up, it prints a ✗ line.

What this means: The warning is informational — it tells you something is not configured, not that something is broken. Skills that depend on the missing integration will degrade gracefully.

Fix: Run /ops:setup to address the flagged items. Or ignore warnings for integrations you don't use.

---

Missing tools detection

Symptom: A skill silently skips a section (e.g., no WhatsApp section appears in /ops:inbox) with no error.

Cause: Skills check for tool availability before running. If wacli is not found, the WhatsApp section is skipped entirely rather than showing an error. Same for aws, gog, etc.

Verify what's detected:

~/.claude/plugins/cache/ops-marketplace/ops/<version>/bin/ops-setup-detect

Look for false values in the JSON output to identify what's missing.

Fix: Install the missing tool and re-run /ops:setup cli to re-detect.

---

Project registry issues

Skills show "registry.json not found"

Symptom: Several skills exit early with {"error":"registry.json not found"} in their pre-gathered data.

Cause: scripts/registry.json doesn't exist. The plugin ships a registry.example.json but not the actual registry (it's gitignored since it contains your project paths).

Fix:

/ops:setup registry

Or manually copy and edit:

cp scripts/registry.example.json scripts/registry.json
# edit registry.json with your projects

---

CLAUDE_PLUGIN_ROOT is unset

Symptom: Shell scripts in bin/ fail with "CLAUDE_PLUGIN_ROOT unset" or try to read from the wrong path.

Cause: The CLAUDE_PLUGIN_ROOT environment variable is not exported in your shell profile.

Fix:

/ops:setup env

This appends the correct export CLAUDE_PLUGIN_ROOT=... line to your shell profile (~/.zshrc or ~/.bashrc). Restart Claude Code after running.

---

AWS CLI issues

ECS data shows empty

Symptom: /ops:fires or /ops:go shows no ECS data. ops-infra returns {"clusters":[],"summary":"No ECS clusters configured"}.

Cause: Either (a) registry.json has no infra.ecs_clusters entries, or (b) the AWS CLI is not authenticated.

Fix A — Add clusters to registry:

{
  "infra": {
    "ecs_clusters": ["myapp-production"],
    "platform": "aws"
  }
}

Fix B — Authenticate AWS CLI:

aws configure
# or
export AWS_PROFILE=my-profile

Verify with: aws sts get-caller-identity