Troubleshooting
Match an error message or symptom to its cause and fix, area by area.
Updated Oct 4, 202612 minute read
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 |
More in Settings.
Widget and identity
Most widget messages print in the browser console.
| 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 |
To test a key away from your site, open https://median.sh/widget?key=median_pk_....
It shows "Your live widget" for a well-formed key, or "No API key" otherwise.
Messages sent there reach your inbox. Setup steps are in
Install the widget and Identity.
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 |
Tools
| 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 |
Every tool error code is in Tool errors.
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 |
More in Inbox.
| 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 |
Discord
| 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 |
Setup is in Discord.
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 |
More in Work from Slack and Discord.
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 |
More in Issue trackers.
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 |
Contact support
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.