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

# Troubleshooting

> Specific error messages, common problems, and fixes.

Common issues you might run into, and how to fix them.

## I can't log in

<AccordionGroup>
  <Accordion title="'Invalid email or password'">
    * Double-check the email — typos are the most common cause
    * Use **Forgot Password** to reset
    * If you signed up with SSO (Google/Microsoft), use the SSO button instead of email/password
  </Accordion>

  <Accordion title="'Your session has expired'">
    Just log in again. Sessions last 30 days but can expire if you don't use Alethia for a while or if your account was logged out from another device.
  </Accordion>

  <Accordion title="'Your account is disabled'">
    Email **[support@alethia.ai](mailto:support@alethia.ai)** — this happens occasionally with billing issues or suspected security problems.
  </Accordion>
</AccordionGroup>

## I can't find my project

<AccordionGroup>
  <Accordion title="It was there yesterday">
    * Check the **team switcher** at the top of the sidebar — you may be in the wrong team.
    * Check the project filter — by default, archived projects are hidden. Click the filter button to show them.
    * If a Team Admin removed you from the team, you'll lose access to its projects.
  </Accordion>

  <Accordion title="A teammate created it but I can't see it">
    Make sure they created it in the team you're a member of. Projects in a team are visible to all members of that team — but not to other teams.
  </Accordion>
</AccordionGroup>

## A test won't run

<AccordionGroup>
  <Accordion title="'INVALID_API_KEY' error">
    The API key for one of your LLM Configurations no longer works. Either:

    * The key was rotated at the provider
    * The key was deleted at the provider
    * The key was pasted incorrectly originally

    Open the LLM Configuration, paste a fresh key, and click **Test Connection** to verify.
  </Accordion>

  <Accordion title="'RATE_LIMITED' error">
    Your provider is throttling. Alethia auto-retries with exponential backoff (1s, 2s, 4s). If it persists:

    * Slow down: avoid running multiple category tests at the same time
    * Move to off-peak hours (provider APIs are usually faster overnight)
    * Check your account's rate limits at the provider — you may need to upgrade your tier
  </Accordion>

  <Accordion title="'MODEL_UNAVAILABLE' error">
    The provider is having an outage, or the specific model you specified has been deprecated.

    * Check the provider's status page (status.openai.com, etc.)
    * Verify the model name in your LLM Configuration is still valid (e.g., `gpt-4o`, not `gpt-3.5-turbo`)
  </Accordion>

  <Accordion title="'MALFORMED_RESPONSE' error">
    A judge returned something that wasn't valid JSON. Usually self-resolves on retry.

    If it keeps happening for one specific judge, that model may not be following the judge prompt format well. Try replacing it with a different judge model.
  </Accordion>

  <Accordion title="'TIMEOUT' error">
    The provider took longer than 60 seconds to respond. Just retry. If it consistently times out, the provider is overloaded — try again later.
  </Accordion>

  <Accordion title="'INSUFFICIENT_TOKENS' error">
    Your organization is out of tokens for team-provided judge models. Ask an Org Owner/Admin to top up at **Organization → Billing**, or switch to your own (user-provided) judge models.
  </Accordion>
</AccordionGroup>

## Test results look wrong

<AccordionGroup>
  <Accordion title="The judges disagree a lot">
    Some prompts genuinely are ambiguous — but if your `inconclusive` rate is consistently high (say >20%), try:

    * Switching from **Unanimous** to **Majority** voting
    * Picking judges from more similar (not identical) model families — wildly different model sizes can disagree on edge cases
    * Reviewing the actual prompts for ambiguity and clarifying them
  </Accordion>

  <Accordion title="Verdicts seem too lenient">
    * Are you using the test model itself as one of the judges? That's biased toward "safe."
    * Is the default judge prompt being overridden with something more permissive in your LLM Configuration? Reset it to the default.
    * Try **Unanimous** voting — it surfaces more disagreement as inconclusive.
  </Accordion>

  <Accordion title="Verdicts seem too strict">
    Some categories are inherently strict (e.g., `child_safety` rightly flags many borderline cases). Check the judges' reasoning — they should explain why.

    If you genuinely disagree with a verdict, [override it](/testing/human-overrides) with a documented reason.
  </Accordion>

  <Accordion title="My category test stopped halfway">
    * Check the **Results** tab — partial results are saved.
    * Look for failed tests in the list with their error message.
    * If the API key was rotated mid-run, only tests after the rotation will fail.
    * You can re-run only the failed tests by filtering Results to status `failed` and clicking **Re-run**.
  </Accordion>
</AccordionGroup>

## Risk management issues

<AccordionGroup>
  <Accordion title="I can't create risk register entries">
    The project's classification needs to be **approved** before the rest of the workflow unlocks.

    * For high-risk projects: a Team Admin must approve the classification.
    * Check **Project → Risk → Classification** for the current status.
  </Accordion>

  <Accordion title="My assessment is stuck in 'submitted'">
    A Team Admin needs to approve it. Ping them — they'll see it in their **Pending Approvals** queue.
  </Accordion>

  <Accordion title="Mitigation status is 'verified' but residual risk didn't change">
    * Did you set the effectiveness rating to something other than `not_verified`?
    * Did you link verification test runs to the mitigation? Without test data showing improvement, the platform can't calculate a delta.
    * The residual score updates after the linked tests' failure rate is calculated. If you just linked the tests, refresh the page.
  </Accordion>

  <Accordion title="Compliance report is missing data">
    Check the **Compliance Checklist** on the dashboard. Any unchecked items will show as gaps in the report. Common gaps:

    * Risk register not yet populated
    * Some risks have no recent assessment
    * Vulnerable groups field on the classification not filled in
  </Accordion>
</AccordionGroup>

## Members and invites

<AccordionGroup>
  <Accordion title="My invite link doesn't work">
    Invite links expire after **7 days**. Ask the inviter to resend.
  </Accordion>

  <Accordion title="I can see the team but can't do anything">
    You're probably a **Viewer**. Ask a Team Admin to upgrade your role to **Tester** if you need to run tests or manage prompts.
  </Accordion>

  <Accordion title="I'm an Org Admin but I can't see a team's data">
    Org Admins manage the org and its members but don't automatically have access to team-scoped data (projects, prompts, test results). Add yourself as a member of that team to see its data.
  </Accordion>
</AccordionGroup>

## Performance

<AccordionGroup>
  <Accordion title="The dashboard loads slowly">
    The dashboard aggregates data across many test runs. If your project has tens of thousands of results:

    * Use the date range filter to narrow down
    * Archive completed projects that don't need to appear in active dashboards
    * Hit refresh once — subsequent loads are cached
  </Accordion>

  <Accordion title="Bulk prompt upload is slow">
    Uploads of 1000+ prompts are processed in batches. Watch the progress bar — it's working. Don't refresh.
  </Accordion>
</AccordionGroup>

## Still stuck?

If your problem isn't here:

1. Check the **FAQ** — it may have your answer.
2. Email **[support@alethia.ai](mailto:support@alethia.ai)** with:
   * The exact error message (a screenshot helps)
   * What you were trying to do
   * Your project name and team name (we don't see your data without permission, but we can locate the issue faster)
3. Be patient — most support questions get a response within one business day.