Troubleshooting

Connecting

The sign-in window doesn't open

Some clients only start the sign-in when you use the server for the first time, or when you click a button:

• Claude: open Customize → Connectors and connect Ybug. If sign-in fails, disconnect and connect again there.
• ChatGPT: check that Developer mode is on under Settings → Security and login, then open the Ybug app under Plugins.
• Codex: run codex mcp login ybug.
• Claude Code: run /mcp, select ybug and choose Authenticate.
• Cursor: click Connect or Needs login next to ybug in the MCP settings.
• VS Code: click Start above the server entry in mcp.json.

If your browser blocks pop-ups, allow them for the client and try again.

I can't add a custom connector in Claude

On Claude Team and Enterprise plans, members can't add custom connectors themselves. An owner adds Ybug under Organization settings → Connectors first, then each member connects it from Customize → Connectors. See Connect Claude.

On Claude's free plan, you can have one custom connector. Remove another one to add Ybug.

"This authorization request has expired" or "Your session has expired"

The consent screen was open too long, or you signed out of Ybug in between. Close the browser tab and start the connection again from your client.

"Your account is currently unavailable"

Your Ybug user isn't an active member of any team. Ask a team owner to check your membership, or contact us.

Connected, but every call fails with 403

The team you picked on the consent screen can't use MCP. This happens when:

• the team is on the FREE plan, or its plan changed to one without MCP
• your membership in the team was suspended

Check the plans, or connect again and pick a different team.

The assistant sees the wrong team's projects

Each connection covers the one team you picked on the consent screen. The team you last worked in on the dashboard is preselected there, so it's easy to approve the wrong one. Disconnect the assistant under Connected apps, connect again and pick the right team. See Working with more than one team.

Using the tools

The assistant doesn't use Ybug

The server is connected, but the assistant answers without calling any Ybug tool, or says it has no access to Ybug. Usually the tools aren't turned on for that conversation:

• Claude: click + in the message box, open Connectors and turn on Ybug.
• ChatGPT: choose Developer mode from the + menu and select the Ybug app.
• VS Code: use Copilot Chat in Agent mode, and check that the Ybug tools are ticked under Configure Tools.
• Cursor, Claude Code, Codex: check that the server is enabled and shows as connected in the MCP list.

It also helps to name Ybug in the prompt, for example "In Ybug, list the open reports on Acme".

The assistant says "Project not found or not accessible"

• The project may be archived. Archived projects are left out.
• It may belong to a different team than the one you connected. Each connection covers one team.
• You may not have access to that project in Ybug. Ask a team owner.

The assistant can read but not change anything

• On BASIC, triage tools aren't available. Changing status, priority, type and tags and adding comments need STARTUP or COMPANY.
• Missing change permission. If the error mentions the feedback:write scope, the assistant was connected with read access only. Disconnect it under Connected apps and connect again.
• Project permissions. The assistant can only change what you can change. If you can't edit reports in a project, it can't either.
• Tools turned off in the client. If you turned off update_feedback, add_comment or create_tag in your client, as described in Read-only access, turn them back on.

I upgraded, but the triage tools don't show up

Most clients load the list of tools when they connect. Restart the client, or reconnect the server, to load the new tools.

Reports are missing from the results

The assistant is connected, but its answer leaves out reports you know exist. Usually it's the search, not the data:

• Keyword search covers titles and descriptions only. Page URLs, comments and reporter details aren't searched. To find reports about a page, ask the assistant to filter by date or status and then check the URLs.
• Filtering by type excludes untyped reports. "Bug" means reports with the Bug type set. A report that describes a bug but has no type isn't included. Ask for "type Bug or no type" to include them.
• Results come in pages. The assistant gets up to 100 reports per call. If a project has more, it has to fetch the next pages. Ask it how many reports it reviewed, and to read all pages.
• The default order is oldest first. If the assistant reads only the first page, it sees your oldest reports. Ask for newest first, or narrow down by date.
• Assignee names must match. The assignee filter takes a member id, or a name exactly as Ybug shows it. me means the Ybug user who connected the assistant, not the person typing in a shared chat.
• Dates need a timezone. "Since Monday" depends on which timezone the assistant uses. If the edges matter, name the timezone in your prompt.
• Descriptions in lists are shortened. Before sorting or summarizing, the assistant should read long reports in full. Ask it to, if the classification matters.
• Archived projects and other teams aren't included. See Project not found or not accessible.

"Unknown status", "Unknown tag" and similar errors

The assistant used a name that doesn't exist in your project, often a guess like "Done" when your status is called "Resolved". It usually recovers by itself by reading your project's statuses or the team's tags. If it keeps guessing, tell it to check the project's statuses first. See IDs and names.

The assistant describes a screenshot it didn't see

The assistant gets a link to the screenshot, not the image itself. Whether it can open the link depends on your client and model. If its answer depends on the screenshot, ask it whether it actually looked at the image, or open the report yourself. See Screenshot and video links.

The console log or network list is empty

The assistant says a report has no console log or no network requests. That means nothing was recorded, not that nothing went wrong:

• Console recording is off. It's on by default from BASIC up, but it can be switched off under Console recorder in the project's widget setup.
• Network logs aren't turned on. They need STARTUP or higher and are off by default. Turn on Network logs in the project's widget setup. Only reports sent after that include them.
• The report came from the browser extension. Extension reports don't include console logs or network requests.
• Request bodies are never captured. The assistant sees each request's method, URL, status and timing, but not what was sent or returned.

Screenshot links don't open

Screenshot and video links expire after about an hour. Ask the assistant to read the report again to get fresh links.

The assistant resolved or closed a report by mistake

Move it back to the status it had, in the dashboard or by asking the assistant. If you use feedback auto-replies, the reply goes out about a minute after the change. If the report is no longer in the Resolved or Closed category by then, the reply isn't sent.

To keep this from happening, tell the assistant not to resolve or close reports, and do that step yourself.

"Rate limit exceeded"

The assistant made a lot of calls in a short time. The limit is per team, so assistants of everyone in your team share it. The error says how long to wait, usually less than a minute. For big jobs, ask the assistant to work in smaller batches, for example one status or one week at a time, and to narrow the list with filters before it opens reports one by one.

"Ybug tools are temporarily unavailable"

Something on our side is briefly unavailable. The error says how long to wait. If it keeps happening, contact us.

Staying connected

The assistant stopped working after a while

• You disconnected it under Connected apps. Connect again from your client and approve access.
• You left the team or your user was deactivated. Access ends automatically.
• It wasn't used for a long time. A sign-in lasts up to six months, and a connection that hasn't been used for 90 days is removed. Sign in again from your client.

Some clients keep an old sign-in and keep failing instead of asking you again. Clear it and sign in again:

• Claude: disconnect Ybug in Customize → Connectors, then connect again.
• Codex: run codex mcp logout ybug, then codex mcp login ybug.
• Claude Code: run /mcp, select ybug, choose Clear authentication, then Authenticate.
• Other clients: remove the Ybug server and add it again.

Still stuck?

Contact us with the name of your client and the error message you see.