Troubleshooting

This page focuses on the problems teams hit most often after launch.

Production deploys apply committed Prisma migrations on container start, then boot the app.

A Board Does Not Appear on the Portal

Check these first:

1. the board is PUBLIC
2. you are opening the correct workspace subdomain
3. you did not expect a private internal board to show publicly

If the board is meant for customers, review Settings → Boards first.

Guests Can View but Cannot Vote, Comment, or Subscribe

The usual cause is that guest interactions are disabled.

Check Settings → General and confirm Allow guest interactions is enabled.

If it is disabled:

• guests can still view public content
• guests must sign in before they can interact

If the board itself is private, guests should not be part of that workflow at all.

A User Still Cannot Submit Feedback

Work through this sequence:

1. is the board public
2. is the user a team member, signed-in end-user, or guest
3. if they are a guest, are guest interactions enabled
4. are you testing the hosted portal or an embed flow

For embed, access depends on the server-created session rather than the portal guest toggle.

A Roadmap Is Missing or Looks Empty

A roadmap can be empty for several different reasons:

• the roadmap visibility is set to team-only
• the roadmap filters exclude the posts you expected
• the column filters exclude the posts
• the columns are not marked as shown

In Boarbs, an “empty roadmap” is often a filter problem, not a content problem.

Someone Did Not Receive an Email Update

Check these in order:

1. they were subscribed to the post
2. they were not the actor who made the change
3. the change was a public comment, a status change, or a completion event
4. the comment was public rather than internal

Common false assumption:

• changing ETA, assignee, title, or internal notes does not send an email by itself

A Comment Was Added but Nobody Was Notified

Usually one of these is true:

• there were no subscribers on the post
• the actor was the only subscriber
• the comment was internal

Remember that commenting is not the same as subscribing.

An Embed Session Cannot Be Created

Check the integration against these rules:

1. the board ID is valid
2. the API key belongs to the correct organization
3. the target board is either public or owned by that organization
4. you are creating the session on your backend, not in browser code

If you are targeting a private board from the wrong organization, Boarbs should reject the request.

A Returning Embed or Widget User Looks Like a Different User

Usually the session is being recreated with a different identity than before.

Check these first:

1. you send the same stable userId on every identified session
2. you still send email when available
3. you are not relying on email alone for users who can change their address later

For identified embed and widget flows, userId is the primary identity when present and email is the fallback.

Automatic Login Leaves the Visitor Signed Out

If ?sso= does not start a portal session, check these first:

1. the token is a valid, unexpired embed session from POST /api/embed/sessions
2. the session includes an email
3. you opened the portal on the same workspace that owns the session
4. the email does not belong to an organization owner, admin, or other team member

Automatic login never impersonates workspace members. Those people must use normal workspace login.

See Automatic Login.

A Public Link Works, but the Experience Feels Wrong

This usually means the structure is technically valid but not intentional yet.

Review:

• board names
• board descriptions
• roadmap name and visibility
• guest interaction setting
• public vs private tags

Many “broken” portals are actually just unfinished setup choices.

A Teammate Cannot Access the Workspace

Check these basics:

1. the teammate was invited through Settings → Members
2. the invitation was accepted
3. they signed in with the same email that was invited
4. you are looking at member access, not portal end-user access

Settings → Users is not your internal team list.

If You Keep Hitting the Same Issue

Stop debugging the symptom and check the model:

• board visibility
• roadmap visibility
• identity type
• guest interaction setting
• subscriber state

Those five variables explain most day-to-day Boarbs behavior.

Next Steps

• Permissions and Visibility — Use this when access rules are unclear
• How Notifications Work — Use this when email behavior feels inconsistent
• Settings Reference — Use this when you are not sure where the controlling setting lives