What causes "{ex.message}" in apache/superset?

If SECRET_KEY or the permalink salt changed, old permalinks are unrecoverable — create a new permalink and update shared links; keep the SECRET_KEY stable across restarts to prevent recurrence

apache/superset · error · SqlLabPermalinkGetFailedError

{ex.message}

Error message

{ex.message}

What it means

For modern (non-'kv:') permalink keys, GetSqlLabPermalinkCommand decodes the key with the configured salt and fetches the value via KeyValueDAO. Decode/codec errors, missing datasets referenced by the permalink, and KV get failures (DatasetNotFoundError, KeyValueCodecDecodeException, KeyValueGetFailedError, KeyValueParseKeyError) are re-raised as SqlLabPermalinkGetFailedError carrying the inner error's message (get.py:68).

Source

Thrown at superset/commands/sql_lab/permalink/get.py:68

                return json.loads(kv.value)
            except Exception as ex:
                raise SqlLabPermalinkGetFailedError(
                    message=utils.error_msg_from_exception(ex)
                ) from ex

        try:
            key = decode_permalink_id(self.key, salt=self.salt)
            value = KeyValueDAO.get_value(self.resource, key, self.codec)
            if value:
                return value
            return None
        except (
            DatasetNotFoundError,
            KeyValueCodecDecodeException,
            KeyValueGetFailedError,
            KeyValueParseKeyError,
        ) as ex:
            raise SqlLabPermalinkGetFailedError(message=ex.message) from ex

    def validate(self) -> None:
        pass

View on GitHub (pinned to f4587218dd)

Solutions

If SECRET_KEY or the permalink salt changed, old permalinks are unrecoverable — create a new permalink and update shared links; keep the SECRET_KEY stable across restarts to prevent recurrence
Verify any dataset referenced by the permalink still exists (restore or re-create it with the same id), otherwise re-generate the permalink
Treat decode failures on user-supplied keys as 4xx input errors: validate key format/length before calling the command
Check ex.message in logs to distinguish salt mismatch (decode failure) from missing dataset (DatasetNotFoundError)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    GetSqlLabPermalinkCommand(key).run()
except SqlLabPermalinkGetFailedError:
    show_permalink_expired_ui()  # salt mismatch or deleted dataset; regenerate link

Prevention

Keep SECRET_KEY and the permalink salt stable across restarts/upgrades
When rotating secrets, accept that old permalinks expire and communicate it
Verify referenced datasets still exist before relying on old permalinks

When it happens

Trigger: GET /api/v1/sqllab/permalink/<key> with a base64/hashed key that was signed with a different salt (SQLLAB_permalink salt / SECRET_KEY changed between create and read); a permalink that embeds a dataset id which has since been deleted; corrupted or tampered permalink payload that fails codec decoding.

Common situations: SECRET_KEY was rotated or the deployment was rebuilt without preserving config, invalidating all existing permalinks; dataset deleted or re-created with a new id after the permalink was shared; user hand-modified the permalink fragment in the URL.

Related errors

AI-assisted analysis of apache/superset@f4587218dd (2026-08-14). Data as JSON: /api/errors/82f8dd6219ca4701. Report an issue: GitHub.