Superset Troubleshooting

Server-side fixes requiring shell access to the Superset host.

1. Invalid Decryption Key

Error: Invalid decryption key or InvalidToken

Cause: SECRET_KEY changed, encrypted fields in dbs table unreadable.

Fix — run in Superset container:

# Clear encrypted fields
psql -U <db_user> -d <db_name> -c \
  "UPDATE dbs SET encrypted_extra = NULL, password = NULL, server_cert = NULL"

# Clear key_value cache
psql -U <db_user> -d <db_name> -c \
  "DELETE FROM key_value"

# Restart Superset service

Then clear browser cache or use incognito.

2. Dashboard TypeError: Cannot read 'width'

Error: TypeError: Cannot read properties of undefined (reading 'width')

Cause: position_json missing ROW > COLUMN > CHART hierarchy.

Fix: Rebuild position_json. For correct format, see superset-api skill "Dashboard Layout" section.

Run a fix script inside the Superset container:

python /tmp/fix_layout.py

3. viz_type Not Registered

Error: Item with key "scatter_chart" is not registered

Fix: Replace old viz_type. For mapping, see superset-api skill "Available viz_type" section.

Can be fixed via REST API (no server access needed). Use superset-api skill.

4. Pie Chart Label Undefined

Error: Cannot read properties of undefined (reading 'label')

Cause: pie uses metric (singular object), not metrics (plural array).

Fix: Change metrics to metric in chart params. Can be done via REST API.

5. Virtual Dataset Columns Missing

Error: Missing columns in datasource: ['xxx']

Two causes:

1. datasource_id mismatch — Chart points to wrong dataset. Fix via REST API.
2. Column cache stale — SQL changed but columns not synced. Run inside Superset container:

from superset import create_app, db
from superset.connectors.sqla.models import SqlaTable
app = create_app()
with app.app_context():
    ds = db.session.query(SqlaTable).filter_by(id=DATASET_ID).first()
    for col in ds.columns:
        db.session.delete(col)
    ds.sync_columns_from_metadata(db.session)
    db.session.commit()
    print('Synced')

6. SQL Lab Hanging

Cause: No Celery worker but allow_run_async=True.

Fix — run inside Superset container:

from superset import create_app, db
from superset.models.core import Database
app = create_app()
with app.app_context():
    d = db.session.query(Database).filter_by(database_name='<database_name>').first()
    d.allow_run_async = False
    db.session.commit()

7. Databricks Token Update

Must update password field (not encrypted_extra):

from superset import create_app, db
from superset.models.core import Database
app = create_app()
with app.app_context():
    d = db.session.query(Database).filter_by(database_name='<database_name>').first()
    d.password = '<new_token>'
    db.session.commit()
    print('Updated')

General Notes

• All Python scripts above should be run inside the Superset application context (container or virtualenv).
• All psql commands require access to the Superset metadata database.
• Restart the Superset service after making config or database changes.
• deploy/.env and similar env files contain secrets — do NOT commit to git.