Troubleshooting

Match an error message or symptom to its cause and fix, area by area.

Search this page for the exact text you see. Messages are copied from the app.

Access and roles

Symptom or message	Cause	Fix
Billing or API is missing from Settings	You are a member	Ask an admin or owner. See Roles
Only admins and owners can see logs.	You are a member	Ask an admin or owner
Only admins and owners can change these settings.	You are a member on General, Agent, Site or another settings page	Ask an admin or owner to make the change
A message starting “Only admins and owners can”, such as “Only admins and owners can manage the knowledge base.”	A member tried an admin action, often from the API, the CLI, MCP or the assistant	Ask an admin or owner
You cannot manage admins.	An admin tried to change or remove another admin	Ask an owner
You cannot change your own role. Ask another owner.	You asked the assistant, the API, the CLI or MCP to change or remove your own membership	Ask another owner, or leave on Settings → General
Assign another owner before leaving this organization.	You are the last owner	Make someone else an owner on Settings → Members, then leave
This invitation is no longer valid	The invitation was used, revoked, is older than 14 days, or its organization was deleted	Ask for a new one
This invitation is for jane@acme.com	You are signed in with another address	Sign out, then sign in with the invited address
You can be in 50 organizations at once. Leave one to make room.	You belong to 50 organizations	Leave one on its Settings → General
Email did not send, followed by a reason	The invitation email failed. The invitation still works	Press Copy link and send the link yourself
You cannot find an organization	It is under another account, or you have not accepted its invitation	Check the organization switcher and the account you signed in with

Symptom or message	Cause	Fix
Median: the apiKey passed to <MedianSupport> is …, which does not look like the browser-safe id	`apiKey` is not a public key	Pass the `median_pk_` value from Settings → API, or `publicKeyFromMedianKey(MEDIAN_KEY)`
Median did not recognize the apiKey passed to <MedianSupport>, so it has been hidden.	The key was revoked or mistyped, or its organization was deleted	Use a live key from Settings → API
Median: <MedianSupport> was given neither apiKey nor identity, so nothing is on the page.	Neither prop is set	Pass `apiKey` or `identity`
Median: could not read the identity route.	The identity route failed or did not answer with JSON	Open the route in the browser and check your server logs
The identity route answers 500 with `missing_median_key`	`MEDIAN_KEY` is not set on the server	Add it to the server environment
Median: the user hash passed to <MedianSupport> did not match.	The hash signs a different string, or was made with another key	Sign the exact `user.id` with the Median key that produced the widget’s public key
Median: a user hash was passed to <MedianSupport>, but its widget id and hash came from different Median keys.	Two keys mixed	Derive both from the same Median key
The widget shows Sign in to chat	`requireSignIn` is on and the identity route says nobody is signed in	Sign in, and check the route returns the user. See Require sign in
Median: <MedianSupport> hit an error and has been hidden. Your page is unaffected.	An unexpected error	Reload. If it repeats, contact support with the console output
The widget has no styling	The stylesheet is not imported	Import `@mediansh/widget/styles.css` once

Knowledge

Symptom or message	Cause	Fix
A document shows Indexing	It is still being processed. The agent cannot use it yet	Wait
Failed, and the document says “Indexing is paused. Check available credits or try again later.”	The organization is on Explore, or out of credits	Upgrade or add credits on Billing, then open the document and press Try again
This file format cannot be imported. Try a text-based PDF, Markdown, or plain text file.	Unsupported file	Convert it and upload again
This file is password protected. Remove the password first.	Encrypted file	Remove the password and upload again
This document could not be read. Export a new copy and upload it again.	Damaged file	Export again
This document exceeds the conversion limit. Split it into smaller files.	File too large to convert	Split it
Needs fixing on the home page says a repository is not syncing	GitHub sync failed	Check the Median GitHub App can still see the repository. See Connected sources
Notion will not show this page. Share it with Median, then try again.	The page is not shared with Median	Share it in Notion
The Notion connection expired. Connect it again, then retry.	Notion access lapsed	Reconnect Notion
Website import is disabled, with “Available on Standard and Pro.”	Explore plan	Upgrade
Answers quote an old version of a GitHub or Notion page	Repositories refresh at most once a minute and Notion at most every 15 minutes, when the agent starts a reply	Press the refresh button at the top of Knowledge. Its tooltip starts Pull fresh copies from
Answers never link the page	The document has no published link	See Published links
The agent does not know something	Nothing in Knowledge covers it	Add a document. See Knowledge

Symptom or message	Cause	Fix
Needs fixing says a tool endpoint is failing	The last sync failed	Open Agent → Tools. The row reads “Sync failed:” with the reason
Sync failed: The endpoint refused the signature. Open the route once to reconnect it with that deployment’s MEDIAN_KEY.	The server’s `MEDIAN_KEY` is not the key that connected the route, or that key was revoked	Reconnect the route with the current key
Sync failed: The endpoint did not answer. Check the URL and that your server is up.	Server down or wrong URL	Fix the URL or start the server, then Sync
Sync failed: The endpoint did not answer with JSON. Is the URL pointing at the route exported by median()?	The URL is not the tools route	Point it at the route
http://localhost:3000 is this deployment’s own machine, not yours.	A local URL	Put a tunnel in front of your dev server and use its URL
Create a Median key in Settings under API before connecting tools.	No Median key exists	Create one on Settings → API
A tool call is waiting and nothing happens	A `high` risk call waits for a teammate. A `reviewed` call waits for the automated reviewer, which can pass it to a teammate. Unanswered approvals expire after 24 hours	Decide it in the inbox. See Approvals and tool runs and Risk levels

Inbox

Symptom or message	Cause	Fix
The agent stopped answering. The thread reads “You are handling this conversation”, or names a teammate	A teammate replied or took over, which pauses the agent	Press Resume agent
The row is marked Needs a person	The agent handed the conversation to the team	Reply, or press Take over
The agent run failed under a reply	The run hit an error, such as the plan or credits	Expand it. Why it failed shows the error
The visitor got “I’ve asked a teammate to step in. Someone will be with you shortly.” with no reason	The agent run failed	Check the thread for The agent run failed, and the plan on Billing
Resume agent is unavailable, with “Available on Standard and Pro.”	Explore plan	Upgrade
A conversation is gone	The view hides it	Check All, Snoozed, Resolved, Closed and Archived. Delete forever cannot be undone
A visitor’s new message started a new thread	The last one was resolved. The next message after a resolve always starts a new thread	Expected

Email

Symptom or message	Cause	Fix
Mail to the support address never arrives	Email support was off. Mail that arrives while it is off is discarded	Turn it on under Integrations → Email. Ask the sender to write again
Forwarded mail never arrives	Mail with `Auto-Submitted` other than `no`, or `Precedence` of `bulk`, `junk` or `list`, is dropped. Group and list forwarders can add these	Forward from a mailbox to the exact support address
That address already belongs to another organization. Change your slug and try again.	Another organization holds the address this slug gives	Change the slug on Settings → General, then turn email on
Email support is unavailable. Contact Median support.	Email is not available on this deployment	Contact Median support
An email conversation has no reply box, with “Available on Standard and Pro.”	Explore plan	Upgrade
The reply could not be emailed, followed by a reason	The send failed, for example because the organization is out of credits	Fix the cause, then send the reply again
A customer’s email landed on a separate customer	The mail failed sender checks, and the address belongs to a signed-in customer	Expected. See Email

Symptom or message	Cause	Fix
Discord connection was not authorized. Try connecting again.	You declined on Discord’s screen	Press Connect a server again
The connection did not finish. Try again.	The connection was interrupted	Press Connect a server again
That server is already connected to another workspace.	Another Median organization holds the server	Disconnect it there, or run `/median unlink` in the server with Manage Server permission
Bot offline on Integrations → Discord, or “The Discord bot is offline. Try again when it reconnects.”	Median’s bot is not connected	Contact Median support
Pick a ticket channel first.	No Ticket channel is set	Choose one, then post the panel
Posting here failed. Can the bot speak in this channel?	The bot cannot post in that channel	Let the Median bot view and send messages there
New tickets are off. Open tickets keep working.	The tickets switch is off	Turn it on
This server is not connected to Median yet. Connect it from the integrations page.	`/median` ran in an unconnected server	Connect it from Integrations → Discord
Discord integration is unavailable. Contact Median support.	Discord is not available on this deployment	Contact Median support

Slack

Symptom or message	Cause	Fix
Slack connection was not authorized. Try connecting again.	You declined on Slack’s screen	Press Add to Slack again
That Slack workspace is already connected somewhere else in Median.	Another Median organization holds it	Disconnect it there, or have a Slack workspace admin run `/median unlink`
Only a workspace admin can unlink Median.	`/median unlink` from a non-admin	Ask a Slack workspace admin
A private channel is not in the Channel list	The list shows public, unarchived channels only	Pick a public channel
Conversation sync is disabled.	The mirror switch is off	Turn it on and pick a channel
Bot offline on Integrations → Slack	Median’s bot is not connected	Contact Median support
Slack integration is unavailable. Contact Median support.	Slack is not available on this deployment	Contact Median support

Setup is in Slack.

Chat commands in Slack and Discord

Symptom or message	Cause	Fix
`/note` or `/actions` answers with a link	Your chat account is not linked	Open the link while signed in to Median and press Link account. Links expire after 15 minutes
This link has expired	The link is older than 15 minutes	Message the assistant again for a new link
That menu is stale. Run /actions again.	The menu is older than 10 minutes, or the conversation changed since it opened	Run `/actions` again

Issue trackers

A tracker that refuses shows its error on the signal when you accept it. Tracker failures never appear under Needs fixing.

Symptom or message	Cause	Fix
Linear connection was not authorized. Try connecting again.	You declined on Linear’s screen	Press Connect Linear again
Median cannot see any teams in that workspace.	The Linear workspace has no team you can access	Connect a workspace with a team
Linear turned us away. Connect the workspace again.	Access was revoked in Linear	Disconnect, then connect again
GitHub would not open an issue. The Median app needs write access to issues on that repository.	The GitHub App lacks Issues write access	Grant it in the app’s settings on GitHub
That repository has issues turned off.	Issues are disabled on the repository	Turn issues on, or pick another repository
GitHub could not find that repository. Check the app can still see it.	The app lost access	Add the repository to the app’s installation

Billing and limits

Symptom or message	Cause	Fix
No credits left. Paid work is paused until you add more.	The balance is $0	Press Add credits on Settings → Billing
Your organization is out of credits. Add more in Settings, Billing.	Paid work was refused for lack of credits	Add credits
This needs the Standard or Pro plan.	Paid work was refused on Explore	Upgrade. See Plans
This feature requires an eligible paid plan.	The feature is not in your plan	Upgrade, or add the add-on
Available on Standard and Pro.	You are on Explore	Admins and owners press View plans. Members ask an admin or owner
Your last payment failed	The card was declined	Press Update payment
The payment did not go through. Update your payment method in the billing portal and try again.	The card was declined during a change	Update the card with Manage, then try again
Purchases are paused right now	Median has paused purchases	Try again later. Cancelling and payment changes still work
This change was already sent. If your plan has not changed in a minute, start again.	The same change was confirmed twice	Wait a minute, then reload Settings → Billing
We could not complete this billing request. Please try again.	The billing provider failed	Try again
Median manages your plan, so it can’t be changed here.	Median granted the plan	Contact Median support
This quote expired. Close and try again.	The review is more than 10 minutes old	Start the change again
Billing setup is being completed. Please try again later.	Billing is temporarily unavailable	Try again later
`429 rate_limited` with Your organization’s API allowance is temporarily full. Please retry shortly.	The plan’s API limit	Wait for `Retry-After`, or raise the limit with an add-on. See Rate limits
API access is temporarily limited to protect shared capacity. Please retry shortly.	A temporary capacity restriction	Wait for `Retry-After`
API access is temporarily limited because unusual automated traffic was detected. Contact support for review.	A fair use restriction	Contact Median support
Too many requests. Wait a moment and try again.	A separate limit, such as tool syncs or invitation emails	Wait and retry

Press Support, the lifebuoy in the header, or Contact support in the account menu. The support agent can check your organization for problems, retry a failed document, refresh a knowledge source, sync or test a tool endpoint, and resolve, reopen, restore, wake or resume a conversation. It asks before it changes anything. For a bug in Median itself, it can attach the browser errors from your session to the report.

Include	Where to find it
The organization	The organization switcher
The thread ID, such as `W-12`	The inbox list and the thread header
The exact message	The screen, or the browser console
When it happened	Date, time and time zone
The log entry	Logs, open the entry, copy Entry ID
What you already tried

Never paste a median_key_ value into a chat. If one leaks, revoke it on Settings → API and create another.