Skip to docs content
Browse documentation
On this page

Troubleshooting

Contact support

For help with the hosted Minion service at minion.codes, email hello@minion.codes or ask in the Minion community . Include the run id (run_...) or the page you were on when something failed.

Minion's tools don't show up after connecting

Some apps bind MCP tools when a conversation starts. If you authorized in the middle of a chat (Claude Desktop is the usual case), start a new chat and ask the app to list Minion's tools. If they still don't appear, remove the connection and add it again from /app/onboarding.

MCP requests fail with an authorization error

  • OAuth apps (Claude, ChatGPT). Remove the connector, add it again with the MCP URL from /app/onboarding, and approve access when the sign-in window opens. If you belong to more than one team, make sure the team you approved is the one you expect.
  • API keys (Claude Code, Cursor, Codex). Every key expires, and a key unused for 14 days stops working. Create a new one at /app/api-keys. Owners and admins can see and revoke every member's keys.
  • Revoke or review connected apps at /app/connections.

The host never opens the Minion authorize window

Dynamic OAuth needs the host to open Minion's sign-in page. If adding the connector succeeds but enabling the tool in chat never opens that window, retry from another browser or device. That is a host or environment issue, not a failed Minion registration. Headless hosts can skip OAuth entirely with an API key from /app/api-keys.

Adding a remote MCP server fails with Invalid origin uri or redirect URI errors

That message comes from the remote authorization server, not from Minion being unreachable. Minion identifies as an OAuth client from the deployment origin and redirects to {origin}/oauth/callback. Allow that redirect URI in the MCP server's identity provider. When the authorization server advertises client_id_metadata_document_supported, Minion also presents {origin}/oauth/client-metadata.json as its client id — allowlist that URL only for providers that support it. Then remove and re-add the server. See Connect remote MCP servers . For a home process behind Cloudflare Tunnel and Access, also see Connect a home MCP server and home-mcp-starter .

Search returns no good matches

  • Rephrase the query using domain vocabulary (for example “email”, “jobs”, “webhooks”).
  • Call search({}) for the domain index, then search({ domain }) for one domain's capabilities and guides.
  • entities opens a known ref such as capability:secrets.set. It does not turn an empty ranked query into better matches — rephrase or browse by domain instead.

Package checks fail with isolate memory or CPU limits

Bundle validation and publish run in a short-lived isolate. A large npm dependency graph can exceed that isolate even when ad hoc execute imported the same library. The failure is the graph, not a missing file. Do not vendor the library or switch to a dynamic import. Keep the package as a thin orchestrator and run the heavy work in a process the owner operates. See Offload work that does not fit a Worker isolate .

Saved packages missing

Packages belong to one team. If a package you expect isn't listed, check that the connected app is signed in to the right team, and that the name is the one saved (minion.packages.list() shows every package). Packages other teams saved are never visible.

Fetch or secret errors

  • Host not approved. A secret only works for hosts an owner or admin approved on it. Send them to /app/secrets, or call minion.waiting.list() to find the exact link. Code can't approve a host for itself.
  • A quota or limit message. Errors such as "This organization's free plan allows ..." name the limit and when it resets (00:00 UTC for daily limits). minion.account.usage() shows each limit, and /app/usage shows worker compute for the month. See Runtime and limits .

MCP servers

When Usage is set to Saved packages only, ad hoc execute is blocked but all saved packages in your organization can call that server; the lock is not package-specific. An owner or admin can unlock it on /app/mcp-servers.

Job, webhook, or package app failed

Open Activity at /app/runs (failures first), or ask your agent to use minion.runs.summary, minion.runs.list and minion.runs.get. Successful key-less ad hoc execute calls are not stored there — only execute failures, keyed execute runs (including successes), and other runtime surfaces.