KakeiBuddy Troubleshooting

Backend Does Not Start

Check dependencies:

cd backend
pip install -r requirements.txt

Run with reload:

uvicorn main:app --reload

If the database fails to connect, check DATABASE_URL or PostgreSQL variables. If none are set, the backend uses local SQLite.

Mobile Cannot Reach Backend

Set an explicit API URL:

EXPO_PUBLIC_API_URL=http://localhost:8000

For Android emulator, use:

EXPO_PUBLIC_API_URL=http://10.0.2.2:8000

The app also tries fallback URLs automatically through mobile/utils/api.js.

Expo App Does Not Start

Install dependencies:

cd mobile
npm install
npm start

If Metro cache is stale, restart Expo and clear cache:

npx expo start -c

Lint Errors

Run:

cd mobile
npm run lint

Fix only issues related to your change unless a larger cleanup is intentional.

Admin Login Does Not Work

The backend seeds an admin user with UUID admin. The password comes from ADMIN_PASSWORD or defaults to changeme.

For deployed environments, always set ADMIN_PASSWORD.

Research Export Returns 503 Or 403

• 503 means RESEARCH_EXPORT_TOKEN is not configured.
• 403 means the X-Research-Export-Token header is missing or invalid.

Example:

curl -H "X-Research-Export-Token: $RESEARCH_EXPORT_TOKEN" \
  http://localhost:8000/api/admin/research/export

AI Coach Uses Fallback

The /coach/suggestions response includes fallback_used.

Fallback can happen if:

• backend/ai/ddpg_budget_policy.zip is missing.
• AI dependencies are not installed.
• The policy fails during prediction.

Install the backend AI dependency set when you want the trained policy to run:

cd backend
pip install -r requirements-ai.txt

The fallback is expected behavior and still returns suggestions.

Docker Build Fails

Use the root compose command first:

docker compose up --build

If dependency installation fails, compare the root Dockerfile and backend/Dockerfile. The root Dockerfile includes extra AI packages and filtering for problematic frozen dependencies.

Challenge Templates Do Not Appear

The backend seeds templates from:

backend/004_seed_challenge_templates_50 (1).sql

Make sure this file is present when running the backend from the backend/ directory or through the provided Docker setup.

Local Reset Did Not Delete Backend Records

This is expected. The mobile reset clears local device data only. It does not delete already-uploaded backend research or sync records.

Back to Documentation Home