.png?fit=max&auto=format&n=V5LGcGniNC1X_QJO&q=85&s=8c9ba3ce9a0d0045976180c9f669af26){kind=logo}
Quick reference
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:- A required environment variable is missing (see Environment variables below)
- Port 80 or 443 is already in use by another service
- The database service has not started yet
Checking service status
running. If any service shows exited or restarting, check its individual logs:
Port conflict
If the installer failed because a port is already in use:Database connection failures
Collabase connects to PostgreSQL using theDATABASE_URL environment variable.
1
Check that the database service is running
running. If not, start it:2
Verify the DATABASE_URL is set correctly
Open your The hostname, port, username, password, and database name must all match your PostgreSQL setup.
.env file and check the DATABASE_URL value. It should follow this format:3
Check that the pgvector extension is installed
The pgvector extension is required. If it is missing, connect to the database and install it:
4
Restart the application
After fixing the configuration, restart all services:
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.
1
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.2
Check the Client ID and Client Secret
In Admin → Identity Providers, re-enter the credentials and save again.
3
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.
4
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.
5
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.6
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.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.1
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.
2
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.
3
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.
”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. 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.1
Open Admin → Settings → Mail
Check that a mail provider is configured and enabled.
2
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
3
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.
4
Check the application logs
AI features not responding
Hosted provider (OpenAI, Gemini, Azure, Groq, Anthropic, Infomaniak)
1
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.
2
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.
3
Check the model name
Confirm the model name is spelled exactly as your provider expects — e.g.
gpt-4o-mini not gpt4o-mini.Local Ollama
1
Check that Ollama is running on your server
2
Verify the model is pulled
3
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.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.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:File upload errors
1
Check available disk space
2
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.
3
Restart the application
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.1
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.
2
Open the project's workflow settings
Go to the project, then Settings → Workflow. The status list here is what the board can display.
3
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.
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.
Migration failures
Database migrations run automatically during installation and updates. If a migration fails:1
Check whether pgvector is installed
Migrations that involve vector fields fail if the pgvector extension is not present:
2
Apply the migration manually
If the automated migration fails and the error message references a specific migration file, you can apply it directly:Replace
<migration-name> with the folder name shown in the error output.3
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:Environment variables
Missing or incorrect environment variables are the cause of many startup and authentication failures. Key variables to verify:Getting help
If you cannot resolve an issue using this guide, submit a support request with:- A description of the problem
- The relevant section of the application logs (
docker compose logs collabase-app) - The Collabase version you are running