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

> Solutions to the most common issues with a Collabase installation — database, authentication, email, AI, file uploads, and migrations.

# Troubleshooting

This page covers the most common problems encountered when running a Collabase installation and how to fix them. Start with the quick-reference table, then follow the step-by-step fixes for your specific issue.

***

## Quick reference

| Problem                                            | Most likely cause                                                      | Jump to fix                                                         |
| -------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Collabase is not responding                        | Services not started, port conflict, or startup crash                  | [App not responding](#app-not-responding)                           |
| Cannot connect to the database                     | Wrong connection settings or database service not running              | [Database connection](#database-connection-failures)                |
| Cannot log in                                      | Wrong credentials, SSO misconfiguration, or locked account             | [Authentication problems](#authentication-problems)                 |
| LDAP sync did nothing or stopped with a warning    | Safety guard triggered, misconfigured filter, or directory unreachable | [LDAP sync issues](#ldap-sync-issues)                               |
| SCIM requests fail with "provisioning is disabled" | SCIM provisioning toggle is off, or the token was revoked              | [SCIM provisioning issues](#scim-provisioning-issues)               |
| Emails are not being delivered                     | Mail provider not configured or incorrect SMTP settings                | [Email delivery](#email-not-sending)                                |
| AI features not working                            | Provider not configured, wrong API key, or Ollama not running          | [AI not responding](#ai-features-not-responding)                    |
| File uploads failing                               | Storage permissions, missing folder, or disk full                      | [File upload errors](#file-upload-errors)                           |
| Migration failed during update                     | Database version mismatch or missing pgvector extension                | [Migration failures](#migration-failures)                           |
| Work items are missing from a board                | Their status belongs to a workflow the project no longer uses          | [Work items missing from a board](#work-items-missing-from-a-board) |

***

## App not responding

The first start after installation can take up to 3 minutes. If Collabase still does not respond after that, check the logs:

```bash theme={"dark"}
docker compose -f deployment/docker/docker-compose.release.yml logs -f
```

Look for error messages near the end of the output. Common causes:

* A required environment variable is missing (see [Environment variables](#environment-variables) below)
* Port 80 or 443 is already in use by another service
* The database service has not started yet

### Checking service status

```bash theme={"dark"}
docker compose -f deployment/docker/docker-compose.release.yml ps
```

All services should show `running`. If any service shows `exited` or `restarting`, check its individual logs:

```bash theme={"dark"}
docker compose -f deployment/docker/docker-compose.release.yml logs collabase-app
```

### Port conflict

If the installer failed because a port is already in use:

```bash theme={"dark"}
sudo ss -tlnp | grep ':80\|:443'
```

This shows which process is using the port. Stop that service and restart Collabase.

***

## Database connection failures

Collabase connects to PostgreSQL using the `DATABASE_URL` environment variable.

<Steps>
  <Step title="Check that the database service is running">
    ```bash theme={"dark"}
    docker compose -f deployment/docker/docker-compose.release.yml ps collabase-postgres
    ```

    The status should be `running`. If not, start it:

    ```bash theme={"dark"}
    docker compose -f deployment/docker/docker-compose.release.yml start collabase-postgres
    ```
  </Step>

  <Step title="Verify the DATABASE_URL is set correctly">
    Open your `.env` file and check the `DATABASE_URL` value. It should follow this format:

    ```
    DATABASE_URL=postgresql://collabase:password@localhost:5432/collabase
    ```

    The hostname, port, username, password, and database name must all match your PostgreSQL setup.
  </Step>

  <Step title="Check that the pgvector extension is installed">
    The pgvector extension is required. If it is missing, connect to the database and install it:

    ```bash theme={"dark"}
    docker exec -it collabase-postgres psql -U collabase -c "CREATE EXTENSION IF NOT EXISTS vector;"
    ```
  </Step>

  <Step title="Restart the application">
    After fixing the configuration, restart all services:

    ```bash theme={"dark"}
    docker compose -f deployment/docker/docker-compose.release.yml restart
    ```
  </Step>
</Steps>

***

## Authentication problems

### Forgot password

Use the **Forgot password** link on the login page. This sends a reset email to the address on file. If no email arrives, check that your mail provider is configured correctly in **Admin → Settings → Mail**.

### Account locked

After several failed login attempts, an account may be locked by brute-force protection. An admin can unlock it from **Admin → Users** by clicking the account and selecting **Unlock**.

### SSO not working (Google, GitHub, Microsoft, Okta, Keycloak, SAML)

The standard email and password login is always available at `/auth/login`. Sign in there as an admin and check the identity provider settings under **Admin → Identity Providers**.

<Steps>
  <Step title="Verify the redirect URI matches exactly">
    The redirect URI registered in your provider (Google Cloud Console, GitHub, Microsoft Entra admin center, etc.) must match the URL Collabase is actually running on — including `https://` and no trailing slash.
  </Step>

  <Step title="Check the Client ID and Client Secret">
    In **Admin → Identity Providers**, re-enter the credentials and save again.
  </Step>

  <Step title="Microsoft only: confirm the Tenant ID is set">
    Collabase refuses to save a Microsoft provider without a Tenant ID (Directory ID) — this is expected, not a bug. Copy it from the app registration's **Overview** page in the Microsoft Entra admin center.
  </Step>

  <Step title="Check Allowed email domains">
    If a user reports being unable to sign in while others succeed, check whether **Allowed email domains** is set on that provider and whether the user's email domain is in the list.
  </Step>

  <Step title="Check that NEXTAUTH_URL is set correctly">
    Open your `.env` file and verify `NEXTAUTH_URL` is set to your Collabase URL exactly as users access it — e.g. `https://collabase.example.com`.
  </Step>

  <Step title="Verify NEXTAUTH_SECRET is set">
    The `NEXTAUTH_SECRET` variable must be set to a long, random string. If it is missing or has changed since users last logged in, all sessions are invalidated.
  </Step>
</Steps>

***

## LDAP sync issues

### "This sync would disable an unusually large number of users"

Collabase stops a sync automatically if it would deactivate more than a fifth of your previously-synced users, and asks you to confirm before proceeding.

<Steps>
  <Step title="Check the directory connection first">
    Click **Test Connection** in **Admin → Identity Providers → LDAP**. If it fails, this is a connectivity or credentials problem, not a real change in your directory — fix the connection and sync again rather than forcing it through.
  </Step>

  <Step title="Check the User Search Filter and Base DN">
    A filter or base DN that is too narrow will only match a fraction of your real users, making the rest look like they were removed. Compare the filter against your directory structure.
  </Step>

  <Step title="Only proceed if the drop is genuine">
    If you recently removed a large group of users from the directory on purpose (e.g. after an offboarding event or organizational change), click **Sync anyway** to apply the deactivations.
  </Step>
</Steps>

### "LDAP search returned 0 users"

The sync found no matching entries and stopped without changing anything — this is always treated as a misconfiguration, not a genuinely empty directory, and cannot be forced through.

Check the **Base DN** and **User Search Filter** fields, and confirm the **Bind DN** service account actually has read access to that part of the directory.

### Users are not being created or updated

Confirm the **Email Attribute** field matches the attribute your directory actually populates for that user (e.g. `mail` for OpenLDAP, `userPrincipalName` for Active Directory). Users without a value in that attribute are skipped.

***

## SCIM provisioning issues

### Requests fail with "SCIM provisioning is disabled for this instance"

The **Enable SCIM provisioning** toggle in **Admin → Identity Providers → SCIM Provisioning** is off. Turn it on — this is a separate switch from having a valid token, and both must be true for SCIM to work.

### Requests fail with an invalid or unauthorized token error

The token was revoked, mistyped, or never generated. Go to **Admin → Identity Providers → SCIM Provisioning**, revoke the old token if it still appears, generate a new one, and re-enter it in your identity provider. Tokens are shown only once at creation.

### A profile field is not updating

Check whether the field is one Collabase syncs from SCIM — see the table in [Identity Providers](/admin/identity-providers). Email address changes are never synced through SCIM by design; update the email directly in **Admin → Users** instead.

### Group membership changes are not appearing

Confirm the group and its members were actually assigned to the Collabase application in your identity provider — Collabase only receives group changes your IdP is configured to push.

***

## Email not sending

Collabase sends emails for password resets, notifications, and invitations. These go through the mail provider configured in **Admin → Settings → Mail**.

<Steps>
  <Step title="Open Admin → Settings → Mail">
    Check that a mail provider is configured and enabled.
  </Step>

  <Step title="Verify SMTP settings (if using SMTP)">
    Double-check the host, port, username, and password. Common issues:

    * Port 465 requires SSL; port 587 uses STARTTLS — make sure the setting matches your server
    * Some providers require the full email address as the username, not just the local part
  </Step>

  <Step title="Send a test email">
    Use the **Send Test Email** button in the mail settings to send a test message to your own address. Check your spam folder if it does not arrive.
  </Step>

  <Step title="Check the application logs">
    ```bash theme={"dark"}
    docker compose -f deployment/docker/docker-compose.release.yml logs collabase-app | grep -i mail
    ```

    Error messages here will identify the exact problem.
  </Step>
</Steps>

***

## AI features not responding

### Hosted provider (OpenAI, Gemini, Azure, Groq, Anthropic, Infomaniak)

<Steps>
  <Step title="Verify the API key">
    Go to **Admin → Settings → AI settings → Language model**. Re-enter the API key for your provider and click **Save and test**. API keys expire or get revoked — generate a new one from your provider's dashboard if needed.
  </Step>

  <Step title="Check that CollabaseAI is toggled on">
    The master switch at the top of the **Language model** page must be enabled. If it is off, all AI features are hidden from users.
  </Step>

  <Step title="Check the model name">
    Confirm the model name is spelled exactly as your provider expects — e.g. `gpt-4o-mini` not `gpt4o-mini`.
  </Step>
</Steps>

### Local Ollama

<Steps>
  <Step title="Check that Ollama is running on your server">
    ```bash theme={"dark"}
    curl http://localhost:11434/api/tags
    ```

    This should return a list of installed models. If it fails, start Ollama:

    ```bash theme={"dark"}
    ollama serve
    ```
  </Step>

  <Step title="Verify the model is pulled">
    ```bash theme={"dark"}
    ollama list
    ```

    If the model you configured in Collabase is not in the list, pull it:

    ```bash theme={"dark"}
    ollama pull llama3.2
    ```
  </Step>

  <Step title="Check the Ollama URL in Collabase">
    Go to **Admin → Settings → AI settings → Language model** and confirm the Ollama URL matches where Ollama is actually running. If Collabase is in Docker, use the host machine's IP address instead of `localhost` — e.g. `http://172.17.0.1:11434`.
  </Step>
</Steps>

### The CollabaseAI launcher is missing

The launcher at the bottom centre of the screen appears only when the master switch is on **and** a provider other than **Disabled** is selected. Both conditions are checked in the browser, so users need to reload the page after you save the settings.

### Semantic search returns nothing

Check which provider is configured. Neither Groq nor Anthropic has an embeddings endpoint, and Gemini's embeddings are not wired into Collabase, so with any of the three as the chat provider nothing can be indexed. Switch to a self-hosted, OpenAI, Azure or Infomaniak provider, then re-save a page to confirm indexing works. See [AI Configuration](/admin/ai-configuration).

### The assistant says the provider is unavailable

The chat panel shows one message for every kind of failure, so the banner alone does not identify the cause. Read the application log for the real error:

```bash theme={"dark"}
docker compose -f deployment/docker/docker-compose.release.yml logs collabase-app | grep -i brain
```

***

## File upload errors

<Steps>
  <Step title="Check available disk space">
    ```bash theme={"dark"}
    df -h
    ```

    If the disk is full, free up space or expand the volume before retrying uploads.
  </Step>

  <Step title="Check file storage permissions">
    The application must be able to write to the configured file storage directory. Check that the folder exists and that the process running Collabase has write permission.
  </Step>

  <Step title="Restart the application">
    ```bash theme={"dark"}
    docker compose -f deployment/docker/docker-compose.release.yml restart collabase-app
    ```

    Some permission issues resolve after a clean restart.
  </Step>
</Steps>

***

## Work items missing from a board

A work item that appears in the backlog and in the work item list, but never in any board column, is holding a status that does not belong to the project's workflow. The board builds its columns from that workflow, so a status from anywhere else matches no column and the card is not drawn.

This can affect items created before Collabase started checking the status on save, or items left behind when a project's workflow was switched without mapping every status across.

<Steps>
  <Step title="Find the affected projects">
    Open **Doctor → Orphaned statuses**. The scan lists every project holding such items and how many are affected. An empty result means no project is affected and the cause is elsewhere.
  </Step>

  <Step title="Open the project's workflow settings">
    Go to the project, then **Settings → Workflow**. The status list here is what the board can display.
  </Step>

  <Step title="Move the items onto the current workflow">
    Start a workflow change and map every status that is still in use to one of the new workflow's statuses. Collabase refuses the change while any status in use is unmapped, so nothing can be stranded a second time.
  </Step>
</Steps>

<Note>
  If you would rather fix a single item instead of the whole project, open it and set its status from the detail view. It reappears on the board as soon as its status belongs to the project's workflow.
</Note>

***

## Migration failures

Database migrations run automatically during installation and updates. If a migration fails:

<Steps>
  <Step title="Check whether pgvector is installed">
    Migrations that involve vector fields fail if the pgvector extension is not present:

    ```bash theme={"dark"}
    docker exec -it collabase-postgres psql -U collabase -c "CREATE EXTENSION IF NOT EXISTS vector;"
    ```
  </Step>

  <Step title="Apply the migration manually">
    If the automated migration fails and the error message references a specific migration file, you can apply it directly:

    ```bash theme={"dark"}
    npx prisma db execute --file ./prisma/migrations/<migration-name>/migration.sql
    ```

    Replace `<migration-name>` with the folder name shown in the error output.
  </Step>

  <Step title="Check the database user has sufficient privileges">
    The database user in `DATABASE_URL` must have permission to create tables, indexes, and extensions. If in doubt, grant full ownership:

    ```bash theme={"dark"}
    docker exec -it collabase-postgres psql -U postgres -c "GRANT ALL ON DATABASE collabase TO collabase;"
    ```
  </Step>
</Steps>

***

## Environment variables

Missing or incorrect environment variables are the cause of many startup and authentication failures. Key variables to verify:

| Variable          | Purpose                                          | Example                                                |
| ----------------- | ------------------------------------------------ | ------------------------------------------------------ |
| `DATABASE_URL`    | PostgreSQL connection string                     | `postgresql://collabase:pass@localhost:5432/collabase` |
| `NEXTAUTH_SECRET` | Session encryption key — must be long and random | 32+ character random string                            |
| `NEXTAUTH_URL`    | The public URL of your Collabase instance        | `https://collabase.example.com`                        |

***

## Getting help

If you cannot resolve an issue using this guide, [submit a support request](https://collabase.featurebase.app/en) with:

* A description of the problem
* The relevant section of the application logs (`docker compose logs collabase-app`)
* The Collabase version you are running