Common Issues
Solutions to frequently encountered problems when using FlagShark.
This page covers common issues users encounter with FlagShark and how to resolve them. For specific topics, see the detailed troubleshooting guides linked at the bottom.
Installation Issues
GitHub App Won't Install
Symptoms: The installation flow doesn't complete, or you see an error during setup.
Solutions:
Can't See All Repositories
Symptoms: Some repositories don't appear in the repository selection.
Solutions:
- Check app permissions - FlagShark may only have access to selected repos
- Update installation - Go to GitHub App settings and add more repos
- Verify repository visibility - FlagShark needs at least read access
Detection Issues
Flags Not Being Detected
Symptoms: You've added flags to a PR, but FlagShark doesn't comment on them.
Common causes and solutions:
| Cause | Solution |
|---|---|
| Unsupported language | Check Supported Languages |
| Unsupported SDK | Add custom config in .flagshark.yaml |
| File in excluded path | Check your exclude patterns |
| Flag not in diff | Flags must be in changed lines |
| Webhook not received | Check GitHub webhook delivery |
See Flag Not Detected for detailed solutions.
False Positives
Symptoms: FlagShark detects something as a flag that isn't one.
Solutions:
- Dismiss in PR comment - Reply with
@flagshark-bot ignore "flag-name" - Add to exclusions - Exclude the file pattern in
.flagshark.yaml - Report the issue - Contact support with the false positive example
Duplicate Flags
Symptoms: The same flag appears multiple times in the dashboard.
Causes:
- Flag key has different casing (
enableFeaturevsenable-feature) - Flag used with different SDKs
- Flag detected in different branches
Solution: Standardize flag naming across your codebase. See Flag Naming.
PR Comment Issues
No Comment on PR
Symptoms: FlagShark doesn't post a comment even though flags are present.
Check these:
Comment Not Updating
Symptoms: The comment shows outdated information after pushing new commits.
Solutions:
- Wait for processing - Updates can take a few seconds
- Check for errors - Look in FlagShark dashboard for processing errors
- Force refresh - Comment
@flagshark-bot refreshon the PR
Comment Shows Wrong Information
Symptoms: Flags listed don't match what's actually in the PR.
Causes:
- Cached analysis from previous commits
- Configuration changed mid-PR
- Branch comparison issues
Solution: Request a fresh analysis with @flagshark-bot refresh.
Dashboard Issues
Dashboard Won't Load
Symptoms: The dashboard shows loading spinner indefinitely or errors.
Solutions:
Flags Missing from Dashboard
Symptoms: Flags you know exist aren't showing up.
Causes:
- Flags added via direct push (not PR)
- Repository not connected
- Flags in excluded files
Solution: Run a full repository scan:
Activity Feed Empty
Symptoms: No events appear in the activity feed.
Causes:
- No recent PR activity with flags
- Wrong repository filter selected
- Time range filter excluding events
Solutions:
- Clear all filters
- Expand the time range
- Verify you have connected repositories
Cleanup PR Issues
Cleanup PR Won't Generate
Symptoms: Clicking "Create Cleanup PR" does nothing or shows an error.
Causes:
- Flag usage too complex for automatic cleanup
- File has been modified since flag was detected
- Repository permissions insufficient
Solutions:
- Try regenerating after syncing with latest main
- Manually create the cleanup PR using FlagShark's analysis as a guide
- Check repository write permissions
Cleanup PR Has Errors
Symptoms: Generated cleanup PR has syntax errors or incorrect code.
Solutions:
Cleanup PR Has Conflicts
Symptoms: The cleanup PR shows merge conflicts.
Solutions:
- Resolve conflicts manually in the PR
- Or regenerate the cleanup PR from FlagShark dashboard
- New PR will be based on current main branch
Webhook Issues
Webhooks Failing
Symptoms: GitHub shows webhook delivery failures.
Check the error:
| Error Code | Meaning | Solution |
|---|---|---|
| 401 | Authentication failed | Reinstall the app |
| 404 | Endpoint not found | Contact support |
| 500 | Server error | Retry, contact support if persistent |
| Timeout | Request took too long | Usually resolves itself |
To check webhook status:
Events Not Processing
Symptoms: Webhooks show as delivered but nothing happens.
Causes:
- Event type not supported (only PR events processed)
- Duplicate delivery (already processed)
- Processing queue backlog
Solution: Check your FlagShark dashboard for processing status. If backlogged, events will process eventually.
Performance Issues
Slow Detection
Symptoms: FlagShark takes a long time to analyze PRs.
Causes:
- Very large PRs (many files/lines)
- Complex code patterns
- High service load
Solutions:
- Break large PRs into smaller ones
- Detection usually completes within 30 seconds
- Check status.flagshark.io for service issues
Dashboard Slow
Symptoms: Dashboard takes a long time to load or respond.
Solutions:
- Use filters to reduce data loaded
- Clear browser cache
- Check your network connection
- Report persistent slowness to support
Account & Billing Issues
Can't Access Workspace
Symptoms: You can log in but can't see your workspace.
Causes:
- Not a member of the workspace
- Workspace was deleted
- Invitation expired
Solution: Ask a workspace admin to invite you, or create a new workspace.
Hitting Usage Limits
Symptoms: You receive warnings about usage limits.
Solutions:
- Review your plan limits in Settings > Billing
- Upgrade your plan for higher limits
- Clean up unused repositories to reduce usage
Getting More Help
If your issue isn't covered here:
Related Documentation
- Flag Not Detected - Detailed detection troubleshooting
- Permissions - GitHub permission issues
- Installation - Setup guide
- Configuration - Custom configuration