Skip to main content

Troubleshooting

Start with the failing boundary: client, Firebase Authentication, callable, Storage, Firestore, task dispatch, or report download. Preserve the first structured error code; later UI messages are often less specific.

Flutter environment does not match the project​

Symptoms: dependency resolution fails, generated code will not compile, or analysis differs from CI.

cd acesense-frontend
mise install
flutter --version
flutter pub get
flutter analyze

The repository pins Flutter 3.41.9 and requires Dart ^3.10.3.

Upload is rejected before Storage starts​

requestUploadPath requires all of the following:

  • an authenticated user and, when ENFORCE_APP_CHECK=true is deployed, a valid App Check token;
  • durable AI-processing consent in the user document;
  • an active trial or entitlement;
  • remaining monthly analysis allowance;
  • remaining daily and concurrent upload quota;
  • accepted metadata, duration, and size.

Use the callable's HttpsError code to distinguish unauthenticated, failed-precondition, resource-exhausted, and invalid-argument. Do not create jobs/{id} manually as a workaround.

Storage upload is denied​

The current client uploads the server-issued path videos/{uid}/{sessionId}/{sessionId}_chunk_001.mp4. Storage rules require the authenticated owner and video/mp4; selecting a file with another MIME type can pass metadata validation yet fail the Storage rule. Confirm the user ID, path, and MIME type. If the upload is abandoned, ensure the client called reportUploadFailure.

Job remains pending or uploaded​

Check the job's creation/update timestamps and the function logs for the Storage trigger and task enqueue. A scheduled sweep marks pending or uploaded jobs failed after two hours and releases reserved accounting.

Do not change the status in Firestore. If an immediate retry is justified, use adminRetryJob; otherwise preserve the document for diagnosis.

Job remains processing​

The server, not the Flutter client, owns the long-running timeout. The reconcileStuckJobs schedule fails a processing job after six hours and releases quota idempotently. Inspect provider/dispatch fields and the dispatchGpuJob log before escalating to a provider-specific runbook. GPU provider internals are outside this page's audit scope.

Analysis is done but the report will not open​

Confirm that the job is done and has the expected result or PDF path. Signed download URLs expire; request a fresh URL rather than persisting an old one. The app only offers PDF export when the job contains a real PDF URL. Public session-share links are not implemented, so a share-link control should not be expected.

Admin page signs in but data or actions are denied​

Authentication and authorization are separate. Refresh the ID token, then verify either:

  • admin: true is present in the Firebase ID-token claims; or
  • during the migration period, the token contains a verified email in the canonical allowlist.

Firestore reads are enforced by rules and admin callables by requireAdmin. Fix both layers together. See Admin sign-in.

Docs or launchpad loops back to sign-in​

Both sites are served by an authentication-gating Cloud Function, not by a public static origin. Check browser cookies, the identity-toolkit request, and the relevant docsServer or launchpadServer logs. Session cookies are HttpOnly, Secure, and SameSite=Lax. A newly granted claim requires a fresh ID token before exchanging it for a session.

Verify the repository's Hosting rewrite:

  • SPA sites rewrite all paths to /index.html.
  • Docs and launchpad rewrite all paths to their server function.
  • API Hosting rewrites /v1/** and /mcp to their respective functions.

For docs and launchpad, also confirm the current build was copied into the function's site directory before deployment.

Cloud Functions deploy fails​

Run the package gates first:

cd acesense-auth-function
pnpm lint
pnpm build
pnpm test
pnpm exec firebase deploy --project acesense-prod --only functions

Check the first deploy error, Node.js 22 runtime support, active Firebase project, credentials, and required secret bindings. See Functions deploy failed.

cd acesense-docs
node scripts/check-links.mjs
node scripts/check-freshness.mjs

Fix the content or link before updating last_verified. Historical records or pages outside the active audit scope should retain their older verification date and carry a visible scope note instead of receiving a cosmetic date bump.

GPU Backend (Python)​

GPU-runtime, CUDA/MPS, model, and provider-specific FFmpeg troubleshooting is outside this audit. First prove that the non-GPU control plane successfully created and dispatched the job, then use a freshly verified provider runbook; the historical GPU pages deliberately retain their older verification dates.