Troubleshooting agents

Overview

Agents run on their own, which is what makes them useful. It also means you may not be watching when something goes wrong. An agent that did not start, a step that stopped partway, or a report with the wrong numbers can all look similar at first. The cause is often different, and this article explains what to check.

This article covers:

• Why an agent did not run.
• What to do when a step fails.
• What to check when an app will not connect.
• How native integrations and MCP connections differ.
• Why an app may ask for approval more than once.
• What to do when a model does not complete agent work reliably.
• Why runs may be slow.
• How to check credits used by a failed run.
• How to improve wrong or incomplete results.
• Browser issues.
• What to send support.

How to use this article

Find the row that matches what you see, then go to that section.

What you see	Possible cause	Go to
The agent did not start when expected	Trigger, status, schedule, time zone or credits	The agent did not run
A step shows an error or stops partway	App, input, model or outside service	A step failed
An app shows as disconnected, or a step cannot reach it	Expired sign-in, missing permission or a second account of the same app	An app will not connect
An app works in one chat but not another	The connection may be off for that conversation, or the native connection is being used by default	Native integration versus MCP connection
The same approval keeps appearing	A new connection, a different person or a reconnected app	Repeated approval requests
A model skips steps or ignores apps	The model may not handle tool-using work well	A model does not support agentic work
The run takes a long time or stops without a result	Large input, a file over the limit or a slow outside service	Timeouts and slow runs
Credits went down but the run did not finish	A failed run charged for steps that did not run	Credits used by a failed run
The run finished, but the output is wrong	Prompt, knowledge or step instructions	Results are wrong or incomplete
A page will not load or looks broken	Browser issue	Browser issues
Nothing here fixed it	Support may need to investigate	How to contact support

Open the run and read it step by step. The plan shows the steps, connected apps, knowledge and instructions, which can help you find where the problem began. Admins can also check the audit log for information about who ran an agent, when it ran and what output it produced.

The agent did not run

When an agent did not start as expected, check these items.

Check the trigger

An agent may run on a schedule, when an event happens in a connected app, or when someone starts it. If you built the agent from a chat and did not set a trigger or schedule, it may need to be started manually. Open the agent and check how it is set to run.

Check the agent status

An agent that is switched off, or saved as a draft and not published, will not run automatically. Check that it is published and on. If a teammate edited the agent, check its status again. A saved change creates a new version, and version history shows what changed.

Check the schedule and time zone

A schedule set for 7:00 runs at 7:00 in the time zone used by that schedule. Check the time, time zone and days of the week. A schedule in a different region may run earlier or later than you expect.

Check your credits

Agent runs use credits from the pool shared by your workspace. The credit meter at the top right shows how many credits are left. A Workspace Admin can also set a credit limit for an individual under Workspace Settings, then Members.

The Credit Usage report shows usage over time and by model, provider, task and agent. To open it, click your profile icon in the bottom left and select Credit Usage report.

A step failed

An agent completes work in steps. If one step fails, open the run and find that step. The cause may be the connected app, missing input, the model, a file over the limit or an outside service.

Common causes

Cause	What to check
The connected app refused the request	Reconnect the app and check its permissions
The step had no usable input	Check whether a file, recipient or required field is missing
The model did not complete the task	Try a different model for that step
An outside service was slow or unavailable	Wait and run the agent again, or reduce the amount of data requested

An agent cannot operate tools through your browser, such as clicking through LinkedIn or a CRM. Use a connected app or an MCP connection instead.

When a step fails, the run shows an error. Include that error in a support request if the step keeps failing.

Retry the step

If the cause was temporary, such as a slow app, use the Retry Step control in the execution history, or start the agent again. If the same step fails the same way twice, check the cause before retrying. Agent runs use credits.

Edit the step

Open the failing step and check its app, knowledge and instructions. Make one change at a time, then run the agent again to see whether it fixed the problem. Saving a change to a published agent creates a new version. You can use version history to review earlier versions.

An app will not connect

Most connection problems are related to sign-in, permissions or the account you used.

• Expired sign-in. An app may ask you to sign in again, for example after a password change. Reconnect the app and sign in again. An expired sign-in is not a new connection, so nothing is charged.
• Missing permissions. When you connect an app, WorkLLM asks for permission to perform certain actions. If the needed permission was not approved, or the account cannot access the required folder, sheet or channel, the step may fail. Reconnect the app and approve the permissions it needs. Check that the account you used can open the item directly.
• The wrong account. Each person connects apps using their own login. A teammate’s connection does not give you access to that account. If an agent is shared, each person who runs it may need to connect the apps it uses.
• A second account of the same app. WorkLLM supports one account per app. You can connect one Gmail account and one Salesforce account, but not two Salesforce accounts with different logins. If you manage several client accounts and need a second login for the same app, that is not supported today.

If you sign in again with a different account for an app that is already connected, the new account replaces the existing one. The sign-in is never blocked. The previous credentials are overwritten, and your agents and chats switch to the new account automatically on their next run.

To remove a connection without replacing it, remove the app’s credentials under Workspace Settings. That stops anything running on that connection immediately.

If you need two accounts of the same app at the same time, for example one per client, use a separate workspace for each. Each workspace holds its own connections.

Connection costs

• Connecting an app costs 10 credits the first time. It The charge is per connection, not per app in your workspace. If you disconnect an app and connect it again later, that is a new connection and it costs 10 credits again.
• Re-authenticating an expired sign-in is different. The credentials refresh without creating a new connection, so nothing is charged, and agents and chats use the updated connection automatically. You do not need to reconnect before every task.

Native integration versus MCP connection

WorkLLM connects to apps through native integrations and MCP connections.

	Native integration	MCP connection
What it is	An app integration built into WorkLLM	A way to connect an app that supports MCP, even if it is not in the native integration list
Setup	Connect the app and sign in	Add the connection details for the app and sign in
Control over actions	Set by the integration	You choose which actions are enabled
Per conversation	Used as connected	Can be turned on or off for each conversation
Accounts	One account per app	One account per app
Sharing	Each person connects with their own login	Each person connects with their own login. On a shared thread, you can see the MCP connections teammates have added

Which connection wins when an app is connected both ways

• If an agent has an app connected natively and through MCP, and your MCP connection for it is turned on and working, the agent uses the MCP connection for that app. It does not use the native integration for that app. Other apps the agent uses still run through their native integrations.

Each person runs the agent with their own connections. The agent stores which MCP servers it expects, and WorkLLM matches them to your own MCP connections, first by id and then by name. If you don’t have a matching connection, or it is disabled or still waiting for authorization, the agent falls back to the native integration for that app.

To make the agent use the native integration, turn off your MCP connection for that agent. If the MCP server is unavailable or returns no tools (for example, it needs to be reconnected), the agent also falls back to the native integration.

• To use the MCP connection instead, change the selector with the connection picker in that conversation. Once you choose, the connection applies for the rest of that thread and overrides the default. If you would rather not rely on the picker, switch off the connection you do not want so there is only one active path.
• The same default applies to agent steps. A step uses the native integration unless that step is pointed at the MCP connection. Connections are chosen per step, so one step of an agent can use the native Gmail integration while the next step uses your MCP server.
• If an action is missing, check whether it is enabled for that MCP connection. If an app works in one chat but not another, check whether that conversation is pointed at the native connection or at your MCP connection.
• Once an app is connected through MCP, agents you build can use it. You do not need to connect it separately for every agent.

Repeated approval requests

The first time an agent uses an app, it may ask for your approval. If it asks again, one of these is the usual cause:

• The agent uses several apps. Each app asks for approval separately.
• You connected the same app more than once. Each connection needs its own approval.
• A teammate is running the agent. It uses their connection, so they need to approve it themselves.
• The app was disconnected and reconnected. Reconnecting resets the approval.

If the same app keeps asking after you approve it:

1. Reconnect the app.
2. Approve it when prompted.
3. Run the agent again.

If it still asks, contact support and include the agent name, the app, and when it happened.

A model does not support agentic work

An agent may need to follow a plan, use apps and pass information between steps. Some models may not handle that work reliably. If a model skips steps, ignores connected apps or stops partway through, try a different model for the affected step.

WorkLLM offers more than 200 models. The model picker shows a cost level for each model. You can start with Recommended, use a cost level such as Low, Medium or High, or choose a stronger model for more complex steps and a lighter one for simpler steps. Higher reasoning levels use more credits, so use them when the task needs them.

Timeouts and slow runs

Some runs take longer because the job is large. Others depend on an outside service that is slow or unavailable.

• Large jobs. An agent that reads a large file, searches the web or works through many steps may take longer. Split large tasks into smaller steps and give each step only the information it needs. If you use the same files often, saving them to memory can avoid processing them from scratch each time.
• Outside services. Connected apps and external servers set their own response times and request limits. If a service is slow or busy, wait a few minutes and run the agent again. If the same app keeps timing out, ask for less data, such as one folder instead of an entire drive.
• The step timeout. Each step that runs its own agent has a limit of 5 minutes. If the step hasn’t finished in that time, it stops and fails with a timeout error. This is the total time for the step, whether it is waiting on an app, a database or a model, or is still working. The timer restarts for each step. Scheduled and automated runs also have an overall limit of 30 minutes, after which the run is marked failed.
• Busy schedules. If many agents are scheduled for the same time, try moving some by a few minutes.

File limits

A run can also be slow or fail because a file is larger than WorkLLM accepts. The limit depends on where the file goes.

Files attached to a message or a question:

File type	Limit
Documents, images, code and PDFs	Up to 25 MB each
Video	Up to 150 MB
Audio	Up to 100 MB

You can attach up to 10 files per message or per question.

If a step fails after reading a large file, check the size against these limits before you change the step. If you reuse a file often, save it to memory. WorkLLM processes it once and sends only the relevant parts with each run, which costs fewer credits than attaching the whole file every time.

Credits used by a failed run

A failed run does not charge credits for the step that failed, or for any step that never ran. The steps that completed before the failure were real work, and their credits remain used. If a four-step run fails on step three, you are charged for steps one and two and not for steps three and four.

If you were charged for a step that did not run, email [e-mail] and ask for a refund.

Check your credit usage

• The credit meter at the top right shows the credits left in your workspace.
• Click the dollar icon under an answer to see which model answered and how many credits it used.
• Click your profile icon in the bottom left and select Credit Usage report to see usage over time and by model, provider, task and agent.
• The agent usage report shows who used an agent, how often and how many credits were used.
• An agent run costs about 5 to 30 credits, depending on the number of steps and the models used. Creating an agent is separate work and costs about 10 to 30 credits, so the first run of a new agent includes that. These are estimates, and the actual cost may vary.

Ask for a refund

Email [e-mail] with your workspace URL, the agent name, the date and time of the run, and a screenshot of the failed run and credit usage. Thread IDs are not shown in the product, so support finds the run from the agent name and the time it ran.

Results are wrong or incomplete

If a run finishes but the result is not what you wanted, check the prompt, the knowledge and the output of each step.

• Improve the prompt. Say what you want, the format you want and who the result is for. For example, “summarize the last three emails from this client in five bullet points for a weekly update” is more specific than “summarize the emails”. Describe what a good result looks like and what the agent should avoid.
• Add knowledge. If the agent needs facts about your products, tone or clients, give it the right information. Check that the knowledge is current. If you want a task kept separate from company context, run the agent without memory.
• Check each step. Open the run and read each step’s output in order. Fix the first step where the output went wrong. Change one thing at a time and run the agent again.

Browser issues

WorkLLM supports latest versions of Google Chrome, Apple Safari and Microsoft Edge. There is no minimum version number to track. Keep your browser on the latest public stable release and it meets the requirement.

If a page does not load or a button does nothing, work through these checks in order:

1. Refresh the page.
2. Sign out and sign in again.
3. Clear the browser cache.
4. Turn off extensions that block scripts or pop-ups for a moment.
5. Try a private window.

If the problem happens in only one browser, try another from the list above and tell us which one it was.

How to contact support

If the problem continues, email [e-mail]. Include:

• Your workspace URL.
• The agent name and the exact date and time of the run. Since the thread IDs are not visible in the product, so support locates the run from these details.
• A screenshot of the error, failed step or unexpected result.
• What you expected, what happened instead, and when it happened.

For credit questions, include a screenshot of your credit usage.

Frequently asked questions

Why did my scheduled agent not run?

Check that a trigger or schedule is set, that the agent is published and on, that the time zone and days are correct, and that your workspace has credits.

Will a failed run cost me credits?

The failed step is not charged, and neither are the steps that never ran. Steps that are completed before the failure keep their credits. If you were charged for a step that did not run, email [e-mail] and report it.

What is the difference between a native integration and MCP?

Native integrations are built into WorkLLM. MCP lets you connect an app that supports MCP, even if it is not in the native integration list.

If an app is connected both ways, which one does a prompt use?

The MCP connection is used. When an MCP server for the same app is turned on in the conversation and is working, WorkLLM uses its tools instead of the native integration. To use the native integration for that conversation, turn the MCP server off in the chat’s MCP connections menu. The setting is saved for that thread. If the MCP server is unavailable (for example, it needs re-authorizing), WorkLLM falls back to the native integration.

Why does the agent keep asking for approval?

It may be using another app, another person may be running it with their own connection, or the app may have been disconnected and reconnected.

Can I connect two accounts of the same app, such as two Salesforce logins for different clients?

No. WorkLLM supports one account per app. Bring the other client’s data in as a file or through memory instead.

Which model should I use for an agent?

Start with Recommended. If a step struggles, try another model for that step.

Can an agent click through websites like LinkedIn or a CRM?

No. Agents cannot operate tools through your browser. Use a connected app or an MCP connection.

Why is my agent slow?

The job may be large, a file may be over the size limit, or an outside app may be slow. Split the work into smaller steps and try again after a few minutes.

What should I send to support?

Send your workspace URL, the agent name and the date and time of the run, a screenshot of the problem, and a short note about what you expected and what happened instead.