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

# Troubleshoot common issues in MSP Recapp

> Step-by-step fixes for integration errors, sync failures, unmapped companies, database connection problems, MFA prompts, and missing report data.

This page covers the most common issues you may encounter in MSP Recapp and the steps to resolve them. If a problem persists after following the steps below, contact support from the **Support** page inside the app or visit [app.msprecapp.com/support](https://app.msprecapp.com/support).

<Note>
  For audit-trail purposes, many corrective actions (such as re-saving credentials or changing settings) are recorded in the **Security > Audit Log**.
</Note>

<AccordionGroup>
  <Accordion title="Integration shows 'Error' status">
    An error status on an integration usually means the saved credentials are no longer valid or have been changed in the source tool.

    **Steps to resolve:**

    1. Go to **Integrations** and open the affected integration.
    2. Review the error message shown on the integration card.
    3. Click the three-dot menu on the integration card and select **Settings**, then re-enter the API key or credentials.
    4. Save the integration. The status should update on the next sync.

    If the credentials are correct and the error persists, check whether the API user in the source tool has the required permissions.
  </Accordion>

  <Accordion title="Sync fails with an authentication error">
    An authentication error during sync means the API key or token used by the integration has expired or been revoked in the source tool.

    **Steps to resolve:**

    1. Log in to the source tool (e.g., ConnectWise Manage or HaloPSA).
    2. Regenerate or create a new API key for the MSP Recapp integration user.
    3. Return to MSP Recapp, open the integration, and update the credentials with the new key.
    4. Save and trigger a new sync to confirm the issue is resolved.
  </Accordion>

  <Accordion title="Devices not appearing after sync">
    If a sync completes without error but no devices appear (or fewer devices than expected), check the following:

    1. Confirm the integration is **enabled** — disabled integrations do not sync.
    2. Verify that the sync was actually triggered after enabling the integration. A sync does not run automatically when you enable or save an integration.
    3. Check that the API user in the source tool has permission to list devices/assets.
    4. If you recently used **Clear All Devices** in Settings, you need to trigger a new sync to repopulate device records.
  </Accordion>

  <Accordion title="Companies showing as 'Unmapped'">
    Unmapped companies are integration companies that have not been linked to an internal organization in MSP Recapp.

    **Steps to resolve:**

    1. Go to **Organizations** in the main navigation.
    2. Open the **Unmapped** tab to see all companies awaiting mapping.
    3. For each company, either map it to an existing organization or create a new organization for it.

    Reports and coverage gap analysis only include data for mapped organizations, so completing this step is important for accurate results.
  </Accordion>

  <Accordion title="Free tier: 'Database Connection Required' error">
    This error appears when you are on the Free plan and have not yet connected an external PostgreSQL database.

    **Steps to resolve:**

    1. Go to **Settings > Database**.
    2. Enable the **Use External Database** toggle.
    3. Enter your PostgreSQL connection details and test the connection.
    4. Initialize the schema, then save.

    See [Connecting your own database](/account/database) for the full setup walkthrough.
  </Accordion>

  <Accordion title="Free tier: database connection test fails">
    If the connection test in Settings > Database returns an error, work through the following checklist:

    * **Host** — Make sure the host does not include a protocol prefix (`postgresql://`). Enter only the hostname, for example `db.xxxx.supabase.co`.
    * **Port** — The default PostgreSQL port is `5432`. Verify your provider uses the same port.
    * **Username and password** — Copy these directly from your database provider's dashboard to avoid typos.
    * **Firewall / allowlist** — Some providers (such as Supabase) restrict connections by IP address by default. Add the MSP Recapp server IP, or temporarily set the allowlist to allow all connections to test.
    * **SSL** — MSP Recapp connects with `sslmode=require`. Ensure your database accepts SSL connections.
  </Accordion>

  <Accordion title="MFA required prompt at login">
    If you see a prompt to set up multi-factor authentication when logging in, your workspace administrator has enabled **Require MFA for all users**.

    **Steps to resolve:**

    1. Download an authenticator app such as Google Authenticator, Authy, or 1Password on your device.
    2. Follow the on-screen prompts to scan the QR code and enter the verification code to confirm setup.
    3. Save your backup codes in a secure location.

    Once MFA is configured, you will use your authenticator app for all future logins. If you have lost access to your authenticator app, contact your workspace Admin to reset your MFA.
  </Accordion>

  <Accordion title="User didn't receive invite email">
    Invite emails are sent immediately when an Admin clicks **Send Invitation**, but delivery can occasionally be delayed.

    **Steps to resolve:**

    1. Ask the user to check their **spam or junk folder** — invitation emails can be filtered by some mail providers.
    2. If the email is not in spam, go to **Users > Pending** in MSP Recapp and find the invitation.
    3. Click the **resend** (refresh) icon on the invitation card to send the email again.
    4. If resending fails or the invite has expired, cancel the invitation and create a new one.
  </Accordion>

  <Accordion title="Report shows no data">
    A blank or empty report is usually caused by one of two things: integrations have not been synced, or organizations are not mapped.

    **Steps to resolve:**

    1. Go to **Integrations** and verify that at least one integration is enabled and has been synced recently. Trigger a sync if needed.
    2. Go to **Organizations > Unmapped** and map any unmapped companies to organizations.
    3. Return to the Reports page and regenerate the report.

    If the report still shows no data after syncing and mapping, check that the integration returned device records — open the integration card and look at the device count shown after the last sync.
  </Accordion>
</AccordionGroup>