Skip to main content

Troubleshooting

Common issues and how to resolve them.

Diagnostics​

Start with the status command to get a health overview:

/cst status

This shows:

  • Slack connection status
  • GitHub/GitLab connection status
  • Monitored repositories
  • Recent error log (last 5 events)
  • Webhook delivery status

Slack Issues​

Codestodian doesn't respond to slash commands​

Symptoms: Typing /cst ... does nothing or shows "dispatch_failed".

Causes and fixes:

  1. Bot not in channel — run /invite @codestodian in the channel
  2. App not installed — re-install from codestodian.io/install
  3. Token expired — workspace admins: go to dashboard → Settings → Reconnect Slack
  4. Socket mode disconnected (self-hosted) — restart the bot process; check SLACK_APP_TOKEN

PR notifications not appearing in channel​

Symptoms: PRs are opened on GitHub but no message appears in Slack.

Checklist:

  • Repository is connected: /cst list repos should show it
  • Bot is invited to the target channel: /invite @codestodian
  • GitHub webhook is active: check repo Settings → Webhooks on GitHub
  • Webhook deliveries are succeeding: check the dashboard Webhook Logs

Check webhook status directly:

# Via API
curl https://api.codestodian.io/v1/repos/:repo_id/webhook-status \
  -H "Authorization: Bearer cst_live_..."

Reviewers not receiving DMs​

Symptoms: Reviewers are assigned but don't get a Slack DM.

Causes:

  1. User not linked — the reviewer's GitHub account isn't linked to their Slack account in Codestodian. Ask them to run: /cst link github <github-username>
  2. DM permissions — the user has DMs disabled from apps. They can enable it in Slack preferences → Privacy
  3. Notify reviewers disabled — check: /cst config and verify notify_reviewers: true

GitHub / GitLab Issues​

Webhook not receiving events​

Symptoms: /cst status shows GitHub connected, but events aren't arriving.

Diagnose:

  1. Check webhook deliveries in GitHub:

    • Go to repo → Settings → Webhooks → your webhook → Recent Deliveries
    • Look for failed deliveries (red ✗)

  2. Common causes:

    • Wrong webhook URL — should be https://your-domain.com/webhooks/github
    • Webhook secret mismatch — regenerate and update in both GitHub and your .env
    • IP allow-listing — if your server restricts inbound IPs, add GitHub's webhook IP ranges

  3. Re-register the webhook:

    /cst reconnect github owner/repo

"Repository not found" error​

Symptoms: /cst connect github owner/repo returns "Repository not found".

Causes:

  • The GitHub App isn't installed on that repository or organization
  • The repository is private and the app only has access to selected repos

Fix: Go to GitHub → Settings → Applications → Codestodian → Configure → grant access to the repository.

CODEOWNERS not being respected​

Symptoms: Reviewer routing ignores your CODEOWNERS file.

Checklist:

  • CODEOWNERS is in the repo root, .github/, or docs/ directory
  • Routing strategy is set to expertise: /cst config routing expertise
  • File syntax is valid (test with GitHub's CODEOWNERS syntax checker)
  • Team members are linked (see "Reviewers not receiving DMs" above)

Quality Gate Issues​

PRs aren't being blocked despite gate config​

Symptoms: Quality gate rules in .codestodian.yml don't seem to apply.

Checklist:

  • .codestodian.yml is committed to the default branch (not just a feature branch)
  • File is valid YAML: run npx js-yaml .codestodian.yml to check syntax
  • Gate block_merge: true is set explicitly
  • GitHub branch protection rules must allow Codestodian's status check — add codestodian/quality-gate as a required status check in branch protection settings

Merge still happens despite block​

Codestodian's blocking is implemented via GitHub Checks API. If someone with admin permissions merges while the check is failing, GitHub allows it by default. To prevent admin bypasses:

Go to repository → Settings → Branches → branch protection rule → enable "Do not allow bypassing the above settings".

Self-Hosted Issues​

Bot starts but Slack isn't connecting​

Error: slack_webapi_platform_error: not_allowed_token_type

Cause: SLACK_BOT_TOKEN and SLACK_APP_TOKEN are swapped. BOT_TOKEN starts with xoxb-, APP_TOKEN starts with xapp-.

Database connection errors​

Error: connect ECONNREFUSED 127.0.0.1:5432
  • Verify PostgreSQL is running: pg_isready -h localhost
  • Check DATABASE_URL format: postgresql://user:password@host:5432/dbname
  • Run migrations if this is a fresh install: npm run db:migrate

High memory usage​

If the Node.js process grows unbounded:

  • Enable Redis for session/queue storage (required for production; don't use in-memory fallback)
  • Set NODE_OPTIONS=--max-old-space-size=512 for memory-constrained environments
  • Upgrade to the latest release — memory optimizations are ongoing

Getting Help​

If none of the above resolves your issue:

  1. Check the logs — in /cst status or server logs with LOG_LEVEL=debug
  2. Search GitHub Issues — github.com/codestodian-io/codestodian/issues
  3. Open a new issue — include your Codestodian version (/cst status), platform, and the full error message
  4. GitHub Discussions — for questions and how-to help: github.com/codestodian-io/codestodian/discussions