Skip to main content
Version: Next

Issue Reporting

Learn how to effectively report bugs and request features for Apache Superset.

Before Opening an Issue​

Pre-Issue Checklist​

  1. Search Existing Issues

    Search: https://github.com/apache/superset/issues
    - Use keywords from your error message
    - Check both open and closed issues
    - Look for similar problems

  2. Check Documentation

  3. Verify Version

    # Check Superset version
    superset version

    # Try latest version
    pip install --upgrade apache-superset

  4. Reproduce Consistently

    • Can you reproduce the issue?
    • Does it happen every time?
    • What specific actions trigger it?

Bug Reports​

Bug Report Template​

### Bug Description
A clear and concise description of the bug.

### How to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

### Expected Behavior
What you expected to happen.

### Actual Behavior
What actually happened. Include error messages.

### Screenshots/Videos
If applicable, add screenshots or recordings.

### Environment
- Superset version: [e.g., 3.0.0]
- Python version: [e.g., 3.9.7]
- Node version: [e.g., 18.17.0]
- Database: [e.g., PostgreSQL 14]
- Browser: [e.g., Chrome 120]
- OS: [e.g., Ubuntu 22.04]

### Additional Context
- Using Docker: Yes/No
- Configuration overrides:
- Feature flags enabled:
- Authentication method:

What Makes a Good Bug Report​

✅ Good Example​

### Bug Description
When filtering a dashboard with a date range filter, charts using
SQL Lab datasets don't update, while charts using regular datasets do.

### How to Reproduce
1. Create a dashboard with 2 charts:
   - Chart A: Uses a SQL Lab virtual dataset
   - Chart B: Uses a regular table dataset
2. Add a date range filter (last 30 days)
3. Apply the filter
4. Chart B updates, Chart A shows no change

### Expected Behavior
Both charts should filter to show last 30 days of data.

### Actual Behavior
Only Chart B updates. Chart A still shows all data.
No error messages in browser console or server logs.

### Screenshots
[Dashboard before filter]: attachment1.png
[Dashboard after filter]: attachment2.png
[Network tab showing requests]: attachment3.png

### Environment
- Superset version: 3.0.0
- Python version: 3.9.16
- Database: PostgreSQL 14.9
- Browser: Chrome 120.0.6099.71
- OS: macOS 14.2

❌ Poor Example​

Dashboard filters don't work. Please fix.

Required Information​

Error Messages​

# Include full error traceback
Traceback (most recent call last):
  File "...", line X, in function
    error details
SupersetException: Detailed error message

Logs​

# Backend logs
docker logs superset_app 2>&1 | tail -100

# Or from development
tail -f ~/.superset/superset.log

Browser Console​

// Include JavaScript errors
// Chrome: F12 → Console tab
// Include network errors
// Chrome: F12 → Network tab

Configuration​

# Relevant config from superset_config.py
FEATURE_FLAGS = {
    "ENABLE_TEMPLATE_PROCESSING": True,
    # ... other flags
}

Feature Requests​

Feature Request Template​

### Is your feature request related to a problem?
A clear description of the problem you're trying to solve.

### Describe the solution you'd like
A clear description of what you want to happen.

### Describe alternatives you've considered
Other solutions or features you've considered.

### Additional context
Any other context, mockups, or examples.

### Are you willing to contribute?
- [ ] Yes, I can implement this feature
- [ ] Yes, I can help test
- [ ] No, but I can provide feedback

Good Feature Requests Include​

  1. Clear Use Case

    As a [type of user], I want [feature] so that [benefit].

    Example:
    As a data analyst, I want to schedule dashboard screenshots
    so that I can automatically send reports to stakeholders.

  2. Mockups/Designs

    • UI mockups
    • Workflow diagrams
    • API specifications

  3. Impact Analysis

    • Who benefits?
    • How many users affected?
    • Performance implications?

Security Issues​

🔴 IMPORTANT: Security Vulnerabilities​

DO NOT create public issues for security vulnerabilities!

Instead:

  1. Email: security@apache.org
  2. Subject: [Superset] Security Vulnerability
  3. Include:
    • Description of vulnerability
    • Steps to reproduce
    • Potential impact
    • Suggested fix (if any)

Security Issue Template​

Send to: security@apache.org

### Vulnerability Description
[Describe the security issue]

### Type
- [ ] SQL Injection
- [ ] XSS
- [ ] CSRF
- [ ] Authentication Bypass
- [ ] Information Disclosure
- [ ] Other: [specify]

### Affected Versions
[List affected versions]

### Steps to Reproduce
[Detailed steps - be specific]

### Impact
[What can an attacker do?]

### Suggested Fix
[If you have suggestions]

Issue Labels​

Priority Labels​

  • P0: Critical - System unusable
  • P1: High - Major feature broken
  • P2: Medium - Important but workaround exists
  • P3: Low - Nice to have

Type Labels​

  • bug: Something isn't working
  • feature: New feature request
  • enhancement: Improvement to existing feature
  • documentation: Documentation improvements
  • question: Question about usage

Component Labels​

  • dashboard: Dashboard functionality
  • sqllab: SQL Lab
  • explore: Chart builder
  • visualization: Chart types
  • api: REST API
  • security: Security related

Status Labels​

  • needs-triage: Awaiting review
  • confirmed: Bug confirmed
  • in-progress: Being worked on
  • blocked: Blocked by dependency
  • stale: No activity for 30+ days

Issue Lifecycle​

1. Creation​

  • User creates issue with template
  • Auto-labeled as needs-triage

2. Triage​

  • Maintainer reviews within 7 days
  • Labels applied (priority, type, component)
  • Questions asked if needed

3. Confirmation​

  • Bug reproduced or feature discussed
  • Label changed to confirmed
  • Assigned to milestone if applicable

4. Development​

  • Contributor claims issue
  • Label changed to in-progress
  • PR linked to issue

5. Resolution​

  • PR merged
  • Issue auto-closed
  • Or manually closed with explanation

Following Up​

If No Response​

After 7 days without response:

@apache/superset-committers This issue hasn't been triaged yet.
Could someone please take a look?

Providing Updates​

Update: I found that this only happens when [condition].
Here's additional debugging information: [details]

Issue Staleness​

  • Bot marks stale after 30 days of inactivity
  • Closes after 7 more days without activity
  • To keep open: Comment with updates

Tips for Success​

Do's​

  • ✅ Search before creating
  • ✅ Use templates
  • ✅ Provide complete information
  • ✅ Include screenshots/videos
  • ✅ Be responsive to questions
  • ✅ Test with latest version
  • ✅ One issue per report

Don'ts​

  • ❌ "+1" or "me too" comments (use reactions)
  • ❌ Multiple issues in one report
  • ❌ Vague descriptions
  • ❌ Screenshots of text (copy/paste instead)
  • ❌ Private/sensitive data in reports
  • ❌ Demanding immediate fixes

Useful Commands​

Gathering System Info​

# Full environment info
python -c "
import sys
import superset
import sqlalchemy
import pandas
import numpy

print(f'Python: {sys.version}')
print(f'Superset: {superset.__version__}')
print(f'SQLAlchemy: {sqlalchemy.__version__}')
print(f'Pandas: {pandas.__version__}')
print(f'NumPy: {numpy.__version__}')
"

# Database versions
superset shell
>>> from superset import db
>>> print(db.engine.dialect.server_version_info)

Creating Minimal Reproductions​

# Create test script
# minimal_repro.py
from superset import create_app

app = create_app()
with app.app_context():
    # Your reproduction code here
    pass

Getting Help​

Before Creating an Issue​

  1. Slack: Ask in #troubleshooting
  2. GitHub Discussions: Search/ask questions
  3. Stack Overflow: Tag apache-superset
  4. Mailing List: user@superset.apache.org

Issue Not a Bug?​

Consider:

  • Feature Request: Use feature request template
  • Question: Use GitHub Discussions
  • Configuration Help: Ask in Slack
  • Development Help: See Contributing Guide

Next: Understanding the release process