> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blueaccademy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors

> Diagnose common local runtime and flashcard issues in BlueAccademy.

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.

<Steps>
  <Step title="Check that all containers are running">
    From your project root, inspect the current container states:

    ```bash theme={null}
    docker compose -f infra/docker-compose.yml ps
    ```

    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.
  </Step>

  <Step title="Inspect the Postgres logs">
    Check for startup errors or crash-loop output:

    ```bash theme={null}
    docker compose -f infra/docker-compose.yml logs postgres-db
    ```

    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.
  </Step>

  <Step title="Restart the full stack">
    If the container is stopped or unhealthy, bring everything down cleanly and start again:

    ```bash theme={null}
    docker compose -f infra/docker-compose.yml down
    docker compose -f infra/docker-compose.yml up --build
    ```

    The backend waits for Postgres health before it starts.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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:**

<Steps>
  <Step title="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.
  </Step>

  <Step title="Verify that the seed ran">
    The backend seeds starter data on startup. Check the backend logs:

    ```bash theme={null}
    docker compose -f infra/docker-compose.yml logs backend-api
    ```

    If the seed did not complete cleanly, restart the stack.
  </Step>

  <Step title="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
  </Step>
</Steps>

***

## 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:**

<Steps>
  <Step title="Inspect the file format">
    Every valid line should look like:

    ```text theme={null}
    Question one[TAB]Answer one
    ```

    Replace `[TAB]` with a literal tab character.
  </Step>

  <Step title="Fix or remove malformed lines">
    Correct bad separators or remove malformed lines, then re-import.
  </Step>

  <Step title="Re-import the corrected file">
    Run the import again after correction.
  </Step>
</Steps>

<Warning>
  Do not document `.apkg` import as supported unless the product repo explicitly adds that support path.
</Warning>

***

## 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:**

<Steps>
  <Step title="Wait for service health">
    The frontend depends on backend health. Give the stack time to settle before assuming the app is broken.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Check the frontend container logs">
    ```bash theme={null}
    docker compose -f infra/docker-compose.yml logs frontend
    ```

    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:

    ```bash theme={null}
    docker compose -f infra/docker-compose.yml up --build frontend
    ```
  </Step>
</Steps>

***

## 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:

```bash theme={null}
docker compose -f infra/docker-compose.yml restart backend-api frontend
```

If the error persists, rebuild the services:

```bash theme={null}
docker compose -f infra/docker-compose.yml up --build backend-api frontend
```

***

<Note>
  If none of the steps above resolve your issue, open a bug report on the [BlueAccademy GitHub repository](https://github.com/SimoneParvizi/blueaccademy). Include the full log output from all services:

  ```bash theme={null}
  docker compose -f infra/docker-compose.yml logs
  ```

  Copy the complete output into your issue.
</Note>