Databricks WAF assessment View on GitHub

Use the app

Troubleshooting

Start with Utilities → Diagnostics. It distinguishes a warehouse reading, durable database, audit trail and current identity and links to the page that owns the next action.

The App does not start or returns 502

  1. Read the deployed App and active deployment:

    databricks apps get databricks-waf-assessment --profile <profile> -o json
databricks apps logs databricks-waf-assessment --profile <profile>

  2. Confirm the active deployment succeeded and the App state is RUNNING.

  3. Re-run lifecycle validation and compare the resolved warehouse and Lakebase resources with the deployed bindings.

  4. Confirm the Lakebase branch and database still exist and the App retains CAN_CONNECT_AND_CREATE.

  5. Use upgrade through the lifecycle wrapper if the deployed source, configuration or bindings drifted.

Do not patch the App configuration by hand; the next DAB deployment would replace that untracked change.

permission denied for schema waf or appkit

This is a Lakebase ownership error, not a SQL warehouse permission error. It means the bound database already contains a schema the current App service principal did not create and does not own. waf holds the durable application record; appkit holds AppKit's internal cache. A common cause is starting the server locally against the production database before the first DAB deployment, or reinstalling the App against a retained database without restoring its records through the recovery workflow.

First inspect the schema without changing it:

databricks psql --project <project-id> --profile <profile> -- \
  -d <postgres-database-name> \
  -c "select nspname, pg_get_userbyid(nspowner) from pg_namespace where nspname in ('waf', 'appkit');"

If the records matter, stop and back them up before recovery. Do not try to repair this with CAN USE on the warehouse or with DML grants: startup creates indexes, which requires ownership.

For an intentionally empty installation only, the Lakebase project owner can remove the schema named in the error. Use only the applicable statement:

databricks psql --project <project-id> --profile <profile> -- \
  -d <postgres-database-name> \
  -c "DROP SCHEMA waf CASCADE;"       # when the error names waf

databricks psql --project <project-id> --profile <profile> -- \
  -d <postgres-database-name> \
  -c "DROP SCHEMA appkit CASCADE;"    # when the error names appkit

This permanently deletes every WAF record in that database. The fallback page retries automatically; the current App service principal then recreates and owns the schema without a redeploy. For retained records, use the backup-and-restore workflow into a new database instead of dropping them.

“The plans could not be read” or another page-level 502

Open Diagnostics first. If Database is not answering, fix the Lakebase binding or deployment before retrying the page. If only one record family fails, capture the request time, selected assessment and page, then check App logs for the matching error. Include those details in a bug report, but remove customer data and credentials.

A collector returned nothing or was refused

Open Method → Checks. Filter to the affected pillar or status. Checks names the statement, source and required grant and links back to the run record.

An empty source can be a fact about the selected window rather than the whole estate. Increase the lookback only when that matches the assessment question; do not widen a window solely to make the warning disappear.

The score looks strong but coverage is low

Read coverage and confidence before posture. Unmeasured requirements are excluded, so a score describes only evaluated applicable requirements. Pillars with insufficient evidence are shown as not assessed. Use the Dashboard's coverage follow-ups to answer human-only requirements or restore unreadable evidence.

The answer button is disabled

The guided answer requires a complete outcome record. Select an outcome and provide the required supporting evidence or rationale, accountable owner and next review date. The button enables when all required fields are valid.

A user can read but cannot start or change anything

Mutations require direct membership in assessor_group. Nested group membership is not accepted because the identity API reports direct memberships for this gate. Add the user directly to the configured group or change the DAB variable through a reviewed upgrade.

The wrong workspace appears in validation

Run:

databricks current-user me --profile <profile>

Then unset any DATABRICKS_HOST, DATABRICKS_TOKEN, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET, DATABRICKS_CONFIG_PROFILE or account selector in the shell. The lifecycle wrapper removes these for its child commands, but standalone CLI commands do not.

The scheduled job fails readiness

Read the readiness task output. Verify:

Preview the derived grant report again. Do not replace the principal with an administrator identity simply to make the run green.

A scheduled assessment is not visible where expected

Check schedule_assessment_id. When set, the job uses that exact definition and its scope. When empty, it creates an ad-hoc scheduled run. Confirm that the selected assessment in the App matches the definition the schedule uses.

Improvement work says it is contradicted

The action was recorded as done, but a later comparable assessment still found one of its requirements unmet. Open the action, follow its requirement link and compare the newer evidence. Correct the action record or raise the remaining work; do not edit the finding.

Report movement is unavailable

Two runs are compared only when their assessment scope and methodology are comparable. A changed pillar set, workspace scope, lookback semantics or scoring methodology may make “no comparison” the honest result.

Before raising an issue

Collect:

Raise the right kind of issue →