Skip to main content

Common issues

This page lists quick fixes for common problems.

What you will do​

  • Fix install and config problems
  • Find logs fast
  • Collect the right info for support

Steps​

1) Export fails - credentials file not found​

Symptom:

  • Error like "Credentials file not found"

Cause:

  • The selected service account JSON was moved or deleted.

Fix:

  • In the app, select the credentials JSON again.

2) Export fails - Firestore connection failed​

Cause:

  • Wrong service account key
  • Missing permissions

Fix:

  • Check the service account permissions for Firestore.
  • Try a different key.

3) Export fails - docRoot is blank or invalid​

Symptom:

  • Error like "docRoot is blank" or "invalid docRoot"

Fix:

  • Enter a valid participantId
  • Or set a valid docRoot override in config

4) Analyze does nothing - no export CSV found​

Cause:

  • Export was not run
  • Export results are saved in a different folder

Fix:

  • Run Export first
  • Confirm the output folder contains *_export*.csv

5) Excel fails - no *_korea_time.csv found​

Cause:

  • Analyze was not run

Fix:

  • Run Analyze first
  • Confirm the output folder contains files that end with _korea_time.csv

6) Excel output has missing rows​

Cause:

  • Excel export can have a hard limit (for example 50,000 rows per raw sheet)

Fix:

  • Split the input CSV files
  • Or change the limit (developer change)

7) Where are local files?​

  • macOS and Linux: ~/.datacollection_researcher
  • Windows: %USERPROFILE%\\.datacollection_researcher

If you run from source, logs are printed in the terminal.

8) How to report a good bug​

Send:

  • OS version
  • App version (or git commit)
  • Which step failed (Export, Analyze, Excel)
  • Exact error message
  • Terminal output (if any)
  • Related config files (remove secrets)

Common mistakes​

  • Selecting a credentials JSON and then moving the file
  • Running steps out of order (Export - Analyze - Excel)
  • Sharing secrets (service account JSON)

Report issues​

Create an issue in your tracker (GitHub or internal) and attach the info above.