Skip to main content
BlueAccademy currently runs as a local three-service stack. Most problems fall into a few categories: database connectivity, incomplete seed runs, malformed import input, or a frontend/backend mismatch during local development.

​
”No database connection is present”

Symptom: Instead of your deck list, the Flashcards page shows the message:
No database connection is present, so no decks can be shown. Start Postgres or configure a local database, then reload the Flashcards page.
Cause: The backend could not reach Postgres. Usually postgres-db is down, unhealthy, or not reachable through the configured connection string.
1

Check that all containers are running

From your project root, inspect the current container states:
You should see postgres-db, backend-api, and frontend all listed with a running or healthy status. If postgres-db shows exited or is missing entirely, proceed to the next step.
2

Inspect the Postgres logs

Check for startup errors or crash-loop output:
Look for lines like database system is ready to accept connections to confirm a successful start. Common problems at this stage include a port conflict on 5432 (another Postgres instance already running on your host) or a corrupted data volume.
3

Restart the full stack

If the container is stopped or unhealthy, bring everything down cleanly and start again:
The backend waits for Postgres health before it starts.
4

Reload the Flashcards page

Once all three containers show a healthy status, hard-refresh your browser (Cmd+Shift+R / Ctrl+Shift+R) to clear any cached error state and reload the deck list.

​
Decks load but show 0 for New, Learn, and Due

Symptom: Your decks appear in the list, but every deck shows 0 in the New, Learn, and Due columns. Clicking into a deck shows “All caught up!” immediately. Cause: Common reasons:
  • The newCardsPerDay setting is set to 0, so the scheduler introduces no new cards.
  • You have already reached today’s new-card limit and all learning/due cards have been reviewed.
  • The database is freshly created and the seed data hasn’t been applied yet.
Fix:
1

Check the newCardsPerDay setting

Open the Settings panel by clicking the ⚙ icon on the Flashcards page. Confirm that newCardsPerDay is greater than 0. The default is a sensible starting value; if it was accidentally set to 0, update it and return to the deck list.
2

Verify that the seed ran

The backend seeds starter data on startup. Check the backend logs:
If the seed did not complete cleanly, restart the stack.
3

Check your assumptions

Seeing zero counts does not prove the app is broken. It may simply mean:
  • today’s quota is exhausted
  • the deck has no currently due cards
  • your settings are too restrictive

​
Anki import errors

Symptom: After importing a .txt file, the import result banner shows amber text like:
✓ 42 cards imported, 3 errors
The error count and individual error details are listed below the summary. Cause: Import expects plain-text lines with a tab separator between front and back. Fix:
1

Inspect the file format

Every valid line should look like:
Replace [TAB] with a literal tab character.
2

Fix or remove malformed lines

Correct bad separators or remove malformed lines, then re-import.
3

Re-import the corrected file

Run the import again after correction.
Do not document .apkg import as supported unless the product repo explicitly adds that support path.

​
Frontend shows a blank page or fails to load

Symptom: Navigating to http://localhost:5173 shows a blank page, browser error, or the message:
blueaccademy API is running but frontend is not.
Cause: The frontend may still be waiting on backend health, or the frontend build may have failed. Fix:
1

Wait for service health

The frontend depends on backend health. Give the stack time to settle before assuming the app is broken.
2

Hard-refresh the browser

Press Cmd+Shift+R (macOS) or Ctrl+Shift+R (Windows/Linux) to bypass the browser cache and reload from the server. A stale cache can cause a blank page after a rebuild.
3

Check the frontend container logs

Look for build errors or a message indicating the static server failed to start. If you see a non-zero exit code, rebuild the image:

​
Deck operations fail after a local code change

Cause: Frontend and backend can drift during local iteration if only part of the stack was rebuilt or restarted. Fix: Restart both the backend and frontend services together to ensure they are running matching versions:
If the error persists, rebuild the services:
If none of the steps above resolve your issue, open a bug report on the BlueAccademy GitHub repository. Include the full log output from all services:
Copy the complete output into your issue.