Troubleshooting

#My task is not running

The card sits in queued and nothing happens.

Check in this order.

1. Is there a model you can reach? If you have not added a key, agents run on Orbi's shared pool. A band that stays on screen means neither your own key nor the shared pool is reachable, so look at the Settings → API Keys → Models screen.
2. Is the key really valid? Run Connection test in the key row's menu. A key that has expired or has restricted permissions looks entered but does not work.
3. Are you out of credits? No new run starts once the credit ceiling is full, so check what is left under Settings → Plan. Connecting your own key spends credits far more slowly.

The card never moves to queued.

Exactly four things trigger execution. Moving the card to Queued, an @agent mention in a human comment, a flow trigger, and an HTTP POST arriving at an inbound trigger. Creating a card, editing it or writing to a collection does not start execution.

#The task went to Error

Open the card and the reason is in a red banner at the top of the drawer. The same reason also drops into the comment stream, and the Trail tab has the cycle summary. The detailed diagnostic trace (the exception stack trace) is kept on the server and not carried to the interface, so the reason text stays readable for you.

These are the common causes.

What you see in the comment	What it means
Budget ceiling exceeded	The task hit the limit of 10 cycles or 30 agent runs. Completed steps are kept, so carry on with a requeue.
Model unreachable	The API key is invalid, its quota is used up, or the provider is unreachable.
Tool error	An MCP server did not answer, or a tool got unexpected input.

Requeue carries the task on from where it stopped, and completed checklist steps are not redone.

If a run put something on the card, such as a deliverable or a completed step, the card does not go to Error. The work arrives in Review, and whatever the agent noted as missing (a tool it did not have, a part it could not finish) is written in the cycle summary. Error means that nothing usable came out of that run.

#What happens if I requeue a card while it is running?

A new run starts and becomes the card's only owner. The run left behind notices this before its next step and stops. It writes nothing to the card's state, history or error banner, and only says so in a comment. The new run sees that comment and carries on from there. The credit spent up to that point is not refunded, so do not requeue a card the moment you suspect it is stuck. If the step list in the Trail tab is still moving, the work is alive. Orbi notices a genuinely stalled run on its own and moves the card to Error, and you can requeue it after that.

#If I keep hitting the budget ceiling

This is usually a sign that the task is too big. There are two fixes.

• Split the task up. Instead of "analyse 10 competitors", open two tasks with five competitors each.
• Assign it straight to an agent instead of the Orchestrator. The planning layer is skipped and no cycles are spent.

#My upload is stuck in pending

After a file is uploaded, text extraction runs in the background and the status moves to complete. If it is stuck on pending, there are three possibilities.

• The file may be too large. A 500-page PDF or a many-sheet Excel file takes time.
• The format may not be supported. The list of supported formats is in Files and artifacts.
• If it is a scanned PDF, an OCR step runs and takes longer, and it needs a model that supports images.

If the status shows no_text_layer, the file has no text layer and OCR produced nothing either. The document is most likely a low-resolution scan.

#The agent does not read my file or cannot find it

• Check the mention name. The @file.<name> mention uses the file's name, not its original filename. You can see and change the name on the Files page.
• Is the file's scope right? A project-scoped file is not visible from a task in another project.
• The file may be in the trash. A deleted file is not resolved by a mention.
• If you are pointing at a very old state of the file, its content may have been cleared, because the last 10 states are kept in the history. Those states are marked in the history list.

#The agent will not update my file

This is by design, because agents cannot update files you upload. Inputs are read-only and the agent writes its result as a new file. That way your source stays where it is.

There are two other things agents cannot do, rename a file and change its scope. Those are your decisions.

#The agent keeps writing the same data again

Semantic duplicate prevention runs when writing to a collection, but an agent can deliberately pass it with force_write. The card's Trail tab shows which tools were called.

If it keeps happening, sharpen the field's purpose (the pencil icon next to the field title), because the agent reads that description while deciding what to write there.

#My agent does not remember the last conversation

The conversation itself does not carry over, and that is by design, because every run starts clean. What carries over is the lasting lesson distilled from that conversation. A standing instruction you give in chat turns into a memory note and is brought back to the agent at the start of later runs (Workspace memory). So "what did we talk about last time" does not come along, while "do it this way from now on" does.

Knowledge that has to last goes in one of four places.

Place	What for
Project description	Lasting rules that hold on every run
The agent's job description	Behaviour that agent always follows
A collection	Data that has to accumulate and be queried
A memory note	Short lessons and preferences learned from runs

More in Memory and context.

#My flow did not run

• It may have been skipped because of an overlap. If a new trigger arrives while the previous run is still going, it is skipped. You can see this in the run log.
• It may be paused. Check its state on the Flows page.
• The time zone may be off. Cron is evaluated in the time zone you picked when you set the flow up.

When you set up a new flow, use Run now to see its output straight away rather than waiting for cron.

#The agent did not reply to my comment

• Was the comment written by a human? An agent's comment never triggers a new run, because that is the infinite-loop guard. Only a human comment triggers one.
• Is the mention written correctly? It must be in the @agent.<name> form, with the agent's full name.
• Every comment is processed once at most, so editing the same comment does not run it again.

#I sent an invite but no email arrived

The invite was created and you see it in the list of pending invites. The invite email is sent in the background, and if the mail server (SMTP) has a temporary fault, delivery is retried automatically at growing intervals. If you do not want to wait, the dialog always shows the invite link. Copy it and pass it on yourself, and the link works the same way. More in Roles, invites and sessions.

The same goes for signing up. The verification email is sent from the same queue and may be delayed, so do not try signing up again. The account exists, so you get a "this email is already registered" error. If the email does not arrive within a few minutes, check your spam folder.

#I forgot my password

Click the "Forgot your password?" link on the sign-in screen and enter your email address. The link you receive lets you set a new password. It is valid for 1 hour, and if it expires you ask for a new one from the same place. After a reset, your sessions on every device are closed for security, and you sign in again with your new password. Adding a password to an account opened with Google or GitHub (and therefore without one) goes through the same flow. More in Roles, invites and sessions.

#I keep having to sign in

Your session normally stays open for weeks. The app refreshes it quietly in the background and you never see the sign-in screen. If you are asked to sign in several times a day, look at Profile → Security → Active sessions.

• If there is a device you do not recognise in the list, change your password, because changing the password drops every other device.
• Devices do not sign each other out. Every device carries its own session, and a session closing on one device leaves the others alone. If all of your devices drop at the same time, one of the three actions that close the whole account was taken, namely changing the password, resetting the password, or Close all sessions on the Profile → Security tab. If none of them was you, change your password.

More in Roles, invites and sessions.

#I cannot see something or there is no button

Check your role. A Viewer only reads. Project management, inviting members, workspace-wide MCP and turning a collection into a screen are Admin only. More in Roles, invites and sessions.

#The agent cannot see the MCP tool I added

The most common cause is this. Adding the connection is not enough, you have to give the agent access to it.

• Orbi (the Orchestrator) uses every workspace connection automatically. If Orbi works but the other agents do not, this is almost certainly why.
• On the Agents page, open the agent's detail, go to the Work tab, tick the connection under "Connection access" and save.
• If you cannot see that section, the agent's place of work is "connects from outside". The setting is not there, and it is right that it is not, because Orbi does not run that agent and the client in your own environment carries its tools (Agents).

If you have given access, check these in order, because the problem is nearly always one of them.

Symptom	Cause	Fix
The connection says "awaiting authorization"	OAuth was not completed	Settings → MCP → Authorize
Works in chat, does not work in a task	The connection is personal and someone else (or an agent) queued the task	Move it to workspace scope if the team will use it
Does not work in a flow run	"Allow in scheduled jobs too" was not ticked when the personal connection was added, or someone else edited the flow	Add the connection with that box ticked, and let the owner edit the flow
None of its tools show up	The connection may be in another workspace, because MCP connections belong to a workspace	Add the connection to the workspace you will use it in
The agent says it cannot use a connection's tool	The tool was not granted to that agent or is turned off on the connection; the agent states which	Check the connection's tools on the agent page or Settings → Tools to enable
The tool list never comes back	The server may be unreachable	Press the "Show tools" button under Settings → Integrations; if the list comes back, the server is fine
The tool call times out	A long-running generation job	Raise Settings → Tool call timeout
It says "I generated it" but there is no file	Image or video generation was still running, and the result was not ready yet when the agent wrote its answer	Ask again a few seconds later and it brings back the result that is now ready

A connection that cannot be reached does not stop the task, those tools are simply skipped.

#My avatar does not show

• If the upload was rejected, the reason may be the format, because only PNG, JPG, WebP and GIF are accepted. SVG is rejected deliberately, because it is an image format that can carry scripts.
• A file with a changed extension is rejected, so the content really has to be that format.
• Files over 5 MB are rejected.
• If the upload succeeded but no image appears, the image processing service may not be configured. In that case the interface falls back to an avatar drawn from your name instead of showing a broken image. If you run your own installation, ask your administrator about the IMGPROXY_KEY and IMGPROXY_SALT settings.

#I cannot find what I am looking for

• File search does not look at the filename, it looks inside the file. Try searching for a sentence from inside a PDF.
• You do not have to remember the folder, because files are narrowed down with type, source and tag facets, and a search is not limited to the folder you are in.
• In this Help Center you can search by pressing the / key.

#Get in touch

If nothing on this page matches your symptom, or you just do not understand why something behaves the way it does, write to us. Both routes land in the same inbox:

• Contact form — orbiwork.space/contact. You do not need to be signed in to fill it in, so it also works when you cannot log in.
• Direct email — platform@orbiwork.space.
• A meeting or a demo — if you would rather talk than write, leave a few times that suit you at orbiwork.space/booking. Confirmation arrives by email and the time can still be changed afterwards, by either side.

The reply goes to the address you write from. The single most time-saving thing you can do is state what you were trying to do and what happened separately; if it is about a task, add the task number too. Never send passwords, API keys or access tokens — they are never needed.