Runbooks

Search returning no results

Symptoms

• Desktop app shows empty results for known patients.

Checks

1. Verify Spanner search indexes exist (see data model).
2. Confirm the organization_id in user claims matches the data.
3. Check search query classification logs for filter issues.
4. Confirm SPANNER_SEARCH_STALENESS_SECONDS is not overly aggressive.

Login or SSO failures

Symptoms

• Login RPC returns unauthenticated or internal errors.

Checks

1. Verify RAVEN_BUBBLE_API_TOKEN secret is present.
2. Confirm Bubble endpoints are reachable.
3. Validate MICROSOFT_CLIENT_ID / tenant settings for SSO.
4. Ensure Firebase Admin credentials are valid.

SSOLogin returns UNAVAILABLE

Symptoms

• SSOLogin returns UNAVAILABLE even for valid tokens.

Checks

1. Confirm MICROSOFT_CLIENT_ID is set in Secret Manager or env.
2. Ensure MICROSOFT_TENANT_ID is correct (default: common).
3. Verify outbound access to Microsoft OIDC discovery endpoints.

Spanner connectivity errors

Symptoms

• RPCs fail with UNAVAILABLE or internal errors.

Checks

1. Validate SPANNER_INSTANCE_ID and SPANNER_DATABASE_ID.
2. Confirm service account has Spanner access.
3. Check Cloud Run networking/VPC configuration if used.

Streaming search stalls

Symptoms

• Client receives RUNNING but never DONE/ERROR.

Checks

1. Confirm client is sending START commands with non-empty query.
2. Inspect logs for cancel events or stream exceptions.
3. Reduce SEARCH_STREAM_BATCH_SIZE to 1 to debug ordering.