Troubleshooting¶

This guide provides solutions to common issues across all reviewGOOSE components. For component-specific troubleshooting, see the FAQ sections in each component's documentation.

Quick Diagnosis¶

Use this flowchart to identify which component is affected:

graph TD
    A[What's not working?] --> B{Can you log in to Dashboard?}
    B -->|No| C[Dashboard Login Issues]
    B -->|Yes| D{Are PRs shown in Dashboard?}
    D -->|No| E[GitHub App Installation Issues]
    D -->|Yes| F{Getting Slack notifications?}
    F -->|No| G[Slack Integration Issues]
    F -->|Yes| H{Getting Goose notifications?}
    H -->|No| I[Goose Issues]
    H -->|Yes| J[Check Component-Specific Docs]

General Issues¶

I'm not sure if reviewGOOSE is working¶

Diagnostic procedure:

Check the Dashboard:
- Navigate to <your-org>.reviewgoose.dev
- Log in with GitHub
- Do you see any PRs listed?
Create a test PR:
- Make a small change in a monitored repository
- Create a pull request
- Wait 60 seconds
Verify each component:
- Dashboard: Refresh and check if PR appears
- Slack: Check configured channel for message
- Goose: Check for desktop notification

If any component fails, proceed to that component's troubleshooting section below.

Nothing works after installation¶

Possible causes:

GitHub App not properly installed
Repository access not configured
Waiting for initial sync

Solutions:

Verify GitHub App installation:
- Go to GitHub Settings → Installed GitHub Apps
- Find "reviewGOOSE"
- Verify it shows "Installed" status
- Check "Repository access" includes your repositories
Wait for initial sync:
- After installation, allow up to 60 seconds for data to sync
- Refresh the Dashboard
Check service status:
- Check Service Status →

PRs are not being tracked¶

Symptoms: Pull requests exist but don't appear in reviewGOOSE.

Solutions:

Verify repository is monitored:
- Go to GitHub Settings → Installed GitHub Apps
- Click "Configure" on reviewGOOSE
- Under "Repository access":
  - If "All repositories": All repos should be monitored
  - If "Only select repositories": Verify your repo is in the list
Check repository visibility:
- Free plan only supports public repositories
- Private repos require Pro or Flock: See Plans
Verify PR is not a draft:
- Draft PRs are tracked but not assigned reviewers
- Mark PR as ready for review
Force a refresh:
- Close and reopen the PR
- This triggers a full resync

GitHub App Issues¶

GitHub App installation failed¶

Symptoms: Error during GitHub App installation or configuration.

Solutions:

Verify permissions:
- You need Organization Owner or Admin role
- Go to GitHub Organization Members
- Verify your role
Check organization settings:
- Some organizations restrict GitHub App installations
- Go to Organization Settings → Third-party access
- Verify third-party applications are allowed
Try installation again:
- Go to reviewGOOSE Real-Time GitHub App
- Click Configure (if previously installed) or Install
- Follow installation steps
Contact GitHub Support:
- If installation repeatedly fails, this may be a GitHub issue
- Contact GitHub Support

GitHub App was accidentally removed¶

Symptoms: reviewGOOSE stopped working after someone removed the GitHub App.

Solutions:

Reinstall the GitHub App:
- Go to reviewGOOSE Real-Time GitHub App
- Click Install
- Select repositories
- Click Install
Verify data recovery:
- PRs should reappear in the Dashboard within 60 seconds
- Historical data is retained for 28 days

I don't have permission to install the GitHub App¶

Symptoms: "You don't have permission" error when trying to install.

Solutions:

Ask an organization owner:
- Only organization owners and admins can install GitHub Apps
- Contact your organization owner to install
- Provide this documentation link
Request permissions:
- If you believe you should have permissions, ask the org owner to promote you
- Go to GitHub Organization Members

Dashboard Issues¶

Can't log in to Dashboard¶

See Dashboard - Troubleshooting for detailed solutions.

Quick fixes:

Clear browser cookies for *.reviewgoose.dev
Try incognito mode
Verify GitHub OAuth authorization
Check organization membership

Dashboard shows no PRs¶

See Dashboard - Troubleshooting for detailed solutions.

Quick fixes:

Verify GitHub App installation
Check repository access (public vs private)
Force refresh (Ctrl+Shift+R / Cmd+Shift+R)
Wait for initial sync (60 seconds)

Dashboard is slow¶

See Dashboard - Troubleshooting for detailed solutions.

Quick fixes:

Clear browser cache
Use repository filtering to reduce load
Try a different browser
Check internet connection

Slack Integration Issues¶

Slack app not posting to channels¶

See Slack Integration - Troubleshooting for detailed solutions.

Quick fixes:

Verify Slack app installation (Slack → Apps → Manage)
Check channel configuration (in your .codeGROOVE repository's slack.yaml file)
Invite bot to channel: /invite @reviewGOOSE
Verify workspace URL in configuration
Create test PR and wait 60 seconds

Not receiving Slack DMs¶

See Slack Integration - Troubleshooting for detailed solutions.

Quick fixes:

Check Slack notification settings (not muted)
Verify email match (GitHub email = Slack email)
Check DM delay (default 65 minutes if in channel)
Verify bot can send DMs: /goose help

Too many Slack notifications¶

See Slack Integration - Troubleshooting for detailed solutions.

Quick fixes:

Increase DM delay: reminder_dm_delay: 120
Disable daily reminders: daily_reminders: false
Mute noisy channels: mute: true
Use repository filtering

Goose Desktop App Issues¶

Goose icon not appearing¶

See Goose - Troubleshooting for detailed solutions.

Quick fixes by platform:

macOSLinuxWindows

Check if running: ps aux | grep -i goose
Restart: killall goose && make run
Check menu bar settings
Reinstall: make clean && make run

Verify system tray support
Check dependencies: libgtk-3-dev, libappindicator3-dev
Restart: killall goose && ./goose

Check hidden system tray icons (up arrow)
Restart via Task Manager
Run as administrator

No Goose notifications¶

See Goose - Troubleshooting for detailed solutions.

Quick fixes:

Check OS notification permissions
Verify PRs exist (click Goose icon)
Create test PR and wait 60 seconds
Check system volume (for audio notifications)

Goose authentication failed¶

See Goose - Troubleshooting for detailed solutions.

Quick fixes:

Verify GitHub CLI auth: gh auth status
Re-authenticate: gh auth login
Check token permissions (if using GITHUB_TOKEN)
Regenerate token

Notification Issues¶

Not receiving any notifications¶

Systematic check:

Dashboard: Can you see PRs at <org>.reviewgoose.dev?
- If no: GitHub App Issues
- If yes: Continue to step 2
Slack: Did you install the Slack integration?
- If no: Notifications will only appear in Dashboard and Goose
- If yes: Slack Integration Issues
Goose: Did you install Goose?
- If no: Notifications will only appear in Dashboard and Slack
- If yes: Goose Desktop App Issues

Receiving duplicate notifications¶

Symptoms: Getting notified multiple times for the same PR event.

Possible causes:

Multiple notification channels enabled: Slack + Goose both notify (this is expected)
Misconfigured Slack channels: PR posted to multiple channels

Solutions:

If Slack + Goose:
- This is normal behavior - you'll get both
- Disable one if you prefer single-channel notifications
If duplicate Slack messages:
- Check .codeGROOVE/slack.yaml for overlapping channel configurations
- Look for wildcard "*" in multiple channels
- See Slack Integration - Custom Mapping

Notifications are delayed¶

Symptoms: Notifications arrive minutes or hours late.

Expected behavior (with GitHub App installed):

Dashboard: Under 1 second
Slack: Under 1 second
Goose: Under 1 second
Slack DM delay: 65 minutes if user is in channel (configurable)

If notifications are delayed beyond this:

Check GitHub webhook delivery:
- Go to Repository Settings → Webhooks
- Find reviewGOOSE webhook
- Check "Recent Deliveries" for failures
Check service status:
- Rare outages may delay notifications
- Get Support →
Slack workspace issues:
- Check Slack Status
- Slack outages may delay DMs

Configuration Issues¶

YAML configuration not working¶

Symptoms: .codeGROOVE/slack.yaml changes don't take effect.

Common mistakes:

File location: Must be .codeGROOVE/slack.yaml in repository root (note the leading dot)

YAML syntax errors:

# ❌ Wrong - tabs used for indentation
channels:
    engineering:  # This is a tab
        repos:
            - myrepo

# ✅ Correct - spaces used for indentation
channels:
    engineering:  # This is 4 spaces
        repos:
            - myrepo

Incorrect workspace URL:

# ❌ Wrong - includes https://
slack: https://myworkspace.slack.com

# ✅ Correct
slack: myworkspace.slack.com

Typos in repository names:

# Repository names are case-sensitive
channels:
    engineering:
        repos:
            - api-sever  # ❌ Typo: should be "api-server"

Debugging YAML:

Validate YAML syntax:
- Use YAML Lint
- Paste your configuration and check for errors

Test with minimal configuration:

global:
    slack: myworkspace.slack.com

channels:
    test-channel:
        repos:
            - "*"

Verify file is committed:
```
git ls-files | grep .codeGROOVE
```
Should output: .codeGROOVE/slack.yaml
Check file permissions:
- File must be readable (not too restrictive permissions)

Performance Issues¶

High resource usage (Goose)¶

Symptoms: Goose uses excessive CPU or memory.

Solutions:

Reduce polling frequency (future feature - currently fixed at 5 minutes)
Filter organizations:
- Click Goose icon → Organization Filter
- Disable organizations you don't need to monitor
Check for memory leaks:
- Restart Goose daily (or use auto-start on login to restart on reboot)
- Report Issue →

Dashboard slow with many PRs¶

Symptoms: Dashboard takes >5 seconds to load.

Solutions:

Use repository filtering:
- Filter to specific repositories instead of viewing all at once
Close stale PRs:
- Close or merge PRs that have been open for >90 days
- Reduces dashboard load
Contact support:
- Flock customers get priority support
- See Plans

Getting Additional Help¶

If your issue isn't covered here:

Check component-specific documentation:
Open a support issue:

Get Support →

Include: - Component affected (Dashboard, Slack, Goose, GitHub Bot) - Steps to reproduce - Expected behavior - Actual behavior - Screenshots (if applicable)

Information to Include in Support Requests¶

When opening a support issue, please provide:

For all issues:

Component(s) affected
Plan tier (Free, Pro, or Flock)
GitHub organization name
Steps to reproduce

For Dashboard issues:

Browser and version
Operating system
URL you're accessing
Any error messages

For Slack issues:

Slack workspace URL
Repository name
Contents of .codeGROOVE/slack.yaml (if applicable)
Channel name where messages should appear

For Goose issues:

Operating system and version
Installation method (Homebrew, source build)
Error messages from terminal
Output of gh auth status

For GitHub Bot issues:

Repository name
PR URL
Who was assigned (if anyone)
Who you expected to be assigned

Maintenance & Status¶

Service Status¶

To check if reviewGOOSE services are operational:

Check Service Status →
Check recent issues for outage reports

Planned Maintenance¶

Planned maintenance windows will be announced:

Get Support →
At least 48 hours in advance
Typically during low-traffic hours (weekends, late night US time)

Next Steps¶

Review Core Concepts to better understand how reviewGOOSE works
Check Security & Privacy for security-related questions
Read component-specific documentation for detailed configuration options