# Troubleshooting - Obss

Help
Troubleshooting
Fix common problems with model providers, agents, launches, Evals and Insights, Ask Obss, the CLI, the plugin, schedules, and billing.
If you can’t find a fix here, email
support@obss.app
or check the
FAQ
.
Setup and agents
Every page shows a model provider banner
None of your model providers can run models right now. The banner shows on every dashboard page except
Model providers
, which lists each fix.
The banner says
Fix
Experiments and Obss AI need a model provider.
No provider is connected, or your account for a personal provider isn’t connected or needs a sign-in.
Select
Connect models
and check each provider’s state.
Experiments and Obss AI can’t run because
a named provider
isn’t working.
Select the button, which names the fix:
Update credentials
,
Reconnect
,
Switch account
, or
Open provider
.
Experiments and Obss AI can’t run because no model provider is working.
Several organization providers need a fix.
Select
Review providers
.
The banner clears when the provider’s models refresh. The CLI (
obss project ai inspect
) and the plugin (
inspect_project_ai
) return the same problem in
blockers
, with a link to the page where you fix it.
Models are missing after you connect a provider
The models haven’t refreshed, or the provider doesn’t offer them for your key. Gateways such as OpenRouter and Vercel AI Gateway show only the models that they expose for your key.
A model that shows in the provider’s table but not in a model list is still being checked, or your key can’t use it. While the provider shows
Refreshing models
, wait for the
refresh
to finish.
Confirm the connection under
Organization settings → Model providers
.
Open the provider and select
Refresh models
.
Reopen
Manage → Agents
and
Organization settings → Obss AI features
.
An agent lists only the models that use an API it supports, as
Which providers each agent uses
explains.
An agent will not enable or run
The agent has no provider it can use, or the connection is broken.
Connect a provider the agent
supports
under
Organization settings → Model providers
, or a personal integration under
Profile → Integrations
.
Turn on the agent under
Manage → Agents
.
Check the agent’s page for provider notices about missing models or broken connections.
Connect custom agent is not available
Custom agents
are in private beta. Email
support@obss.app
to enable them for your organization.
A custom agent needs attention
The
custom agent
failed to install, start, or answer, or it needs a value.
On the agent’s page under
Manage → Agents
, the
Status
section shows what failed, the agent’s own error, and the fix. Change the setting that the fix names, then select
Test agent
.
If a run failed before the agent answered, the run page shows the same fix with a link such as
Go to Models
.
Ask Obss says it needs a model
No model is set for Ask Obss.
Connect a provider under
Organization settings → Model providers
.
Choose an
Ask Obss model
under
Organization settings → Obss AI features
.
Refresh the page and open
Ask Obss
again.
A Claude Subscription model is missing from Ask Obss
This is expected.
Ask Obss
doesn’t support models from
Anthropic (Claude Subscription)
, although Evals and Insights can use them. Choose an Ask Obss model from another provider, such as
OpenAI (ChatGPT Subscription)
or
Nous Portal
.
Launches and runs
Launch is blocked by the run balance
Your organization doesn’t have enough runs for the launch. Subscribe or top up under
Organization settings → Usage & billing
.
Runs and billing
explains the run balance, and the
Pricing
page lists the plans.
Launch is blocked by turned-off MCP tools
Select
Open treatment
in the message, then fix the cause. Learn more in
Turn off MCP tools
.
Blocker code
Cause
Fix
mcp_tools_off_unsupported
A
custom agent
(private beta) is in the launch, and custom agents can’t turn off MCP tools.
Remove the custom agent, or turn the tools back on in the named treatment. From the CLI and the plugin,
"disabledMcpTools": []
turns every tool back on.
mcp_tools_all_off
A treatment turns off every tool of a server, for example after the server removed the tools that were on.
Turn at least one tool back on, or remove the server from the treatment.
A run could not start because a setup command failed
A setup command exited with an error or timed out, so the agent never started. This covers a machine’s
Custom
installs and
Setup commands
, a CLI’s or SDK’s install command, and a CLI’s
Post-install commands
(
when they run
).
Fix the command and launch again. The blocked run gets no Evals, doesn’t count toward pass rate, and doesn’t use your run balance. Obss doesn’t retry it, because it would fail the same way. The exception is a package install where the registry or mirror didn’t answer: Obss retries that for you.
Dashboard
CLI
Plugin (MCP)
The run page names the failed step, such as
CLI “Elastic CLI” post-install command failed
or
timed out
, with its number when there are several, such as
Machine “Dev box” setup command 3 failed
. Below it are what to fix, the exit code, and the failing output line, such as
npm error 404 Not Found
. Select
Show command and output
for more, or
Open CLI
,
Open Machine
, or
Open SDK
to fix the command.
Timeouts:
all setup commands share one time limit (“Setup reached its 10-minute limit while CLI “Elastic CLI” post-install command was running.”). Shorten the setup commands.
Multi-line install commands
can’t run. Join the lines with
&&
or end each with
\
.
Package installs:
the message names the package manager, such as
npm install failed
, and the machine and tools whose packages it installs, with a link when only one of them declared the packages. Check the package names there.
The experiment page says how many runs couldn’t start and names the failed step, or the most common one when several steps failed. Select the machine’s or tool’s name to open it.
obss
runs
list
--experiment-id
exp_8f2c41d0
--outcome
infra_blocked
--output
json
Each run that a setup command stopped has
setupFailure
, and its
error.message
names the step (
obss runs list
).
obss runs profile
shows the step, what to fix, the
obss resources inspect
command for the machine or tool, and the command and its output.
Your AI assistant calls
List run results
(
list_runs
) with
outcomes: ["infra_blocked"]
and reads
setupFailure
on each run.
Get a run profile
(
get_run_profile
) returns the same field for one run. To fix the command, the assistant reads the machine or tool with
Inspect a resource
(
inspect_resource
).
Each failed step is also a
friction
. Its
Where to fix
names the machine or tool that declared the command, and for a machine the friction page links to it. Every blocked run also has
blockedReason
in the CLI and the plugin, with a
cause
and a one-line
message
.
setupFailure fields
Secret values are redacted, as in the run’s trajectory.
Field
Meaning
owner
The machine, CLI, or SDK step that declared the command: its
kind
,
key
,
name
, and
step
.
null
for a package install.
manager
,
packageOwners
For a package install: the package manager, and the machine and tools whose packages it installs.
commandNumber
The command’s number, from 1, when its owner has more than one command of that kind. Absent otherwise.
command
The command that failed. For a package install, the install command with the packages you declared.
exitCode
The exit code.
null
when the command timed out or Obss couldn’t read the code.
timeoutSeconds
The time limit the command reached. Present only on a timeout.
output
,
outputTruncated
The last output lines.
outputTruncated
is
true
when earlier lines are left out.
A run could not start because of its machine
The run’s machine can’t run it, so the agent never started. The run page names the cause, shows the details under it, and has an
Open Machine
button. Obss doesn’t retry the run, because it fails the same way until you change the machine.
Cause
Fix
A service didn’t become ready
, for example
Service “redis” didn’t become ready
, with what Docker reported, such as “The container exited with code 137.”
Check the service’s image, command, and health check in the machine.
The agent can’t run on this machine’s Node.js
, for example
Codex 0.167.0 needs Node.js >=22. This Machine has Node.js 20.11.1.
Change Node.js in the machine’s setup, or choose another agent.
The CLI and the plugin return the cause, the details, the machine’s
key
and
name
, and for a service its
service
, in
blockedReason
(
machine_service
or
machine_node_version
).
obss runs profile
also prints the
obss resources inspect machine
command for it.
Launch is blocked by saved header values
The launch stops with
mcp_header_values_unbound
when a selected MCP server version would send its saved header values, or its OAuth app’s client secret, to an address that no person bound them to. This happens most often after an AI assistant saves the server at a new URL. The message names the server, the version, and the full address.
Select
Open Tools tab
in the message, or open the blocker’s
setupUrl
from the CLI or the plugin.
If you expect the address, select
Refresh
. If you don’t, save a new version of the server with the correct address instead.
Go back to the launch. The dashboard checks the launch again when you return to its tab.
A run launched before someone entered a value again can stop before it starts for the same reason, with
The run did not start: saved values are not bound
(error code
SIMULATION_MCP_HEADER_VALUES_UNBOUND
in the CLI and the plugin). Bind the values the same way and launch again. The stopped run doesn’t use your run balance. Learn more in
Saved header values and the server address
.
Launch is blocked by a variable name that two places set
The blocker
variable_name_clash
means that two places, such as two MCP servers or a CLI and the agent’s model provider, set the same variable name to different values. The agent gets one value for each name, and only a CLI or SDK can replace a machine variable. The message names both places and the tasks, treatments, or agents it stops.
Select the link in the message, and remove or rename the variable in one place. For a model provider clash, change the task input that the message names. Scheduled launches aren’t stopped by this blocker. Learn more in
When two places set the same variable
.
A run errored or was cancelled
Open the run to read the error, if one was recorded. Fix the cause (the provider, the task’s machine or files, or the treatment’s tools), then launch again. Errored and cancelled runs don’t use your run balance.
The plugin or the CLI cannot accept a secret
This is expected: OAuth sign-ins, API keys, and secret headers are entered only in the dashboard, at the link the tool or command returns.
obss setup links
and
Get secure setup links
(
get_setup_links
) list every machine and tool that still needs a value.
Max Concurrency feels too low
Organization and global limits can keep fewer runs active than your
Max Concurrency
value. Set a lower value yourself when runs use tools that change the same data, so that they don’t overwrite each other’s changes. Learn more in
Set Max Concurrency
.
A schedule is paused or skips launches
A schedule skips a launch while its last experiment is still running (“Skipped the last 3 launches because the previous experiment was still running. Choose a less frequent repeat.”). Choose a less frequent repeat, or cancel the running experiment.
When a launch needs a fix, Obss pauses the schedule and shows
Needs attention
. The schedule page says why and links to the fix:
The schedule page says
Fix
”Some of this experiment’s tasks, treatments, or models no longer exist. Edit the schedule and choose another experiment.”
Select
Edit
and choose another experiment.
The person the schedule runs as is no longer a member of the organization.
Select
Resume
to run it as you.
It runs with a person’s own account, and someone else changed what it launches.
That person reviews the experiment and selects
Resume
.
If the schedule launches its experiment in
Agent mode
and your organization can no longer use it, Obss pauses the schedule and tells its owners in the app and by email: “This schedule launches its experiment again in Agent mode, which your organization can’t use now. Launch the experiment again in Standard mode, point the schedule at the new experiment, and resume the schedule.”
Fix the cause, then select
Resume
next to the fix link.
Resume
checks the launch again, and if something still blocks it, the page lists every problem with its fix link. Learn more in
When Obss pauses a schedule
.
Evals and Insights
Evals or Insights did not run
The models weren’t set, or Evals or Insights was off at launch.
Choose the
Evals model
,
Insights model
, and
Experiment insights model
under
Obss AI features
.
On the experiment, select
Run evals
or
Run insights
.
Learn more in
Evals
and
Insights
.
Evals or Insights could not evaluate a run
The run says “Evals could not evaluate this run, so it has no Pass or Fail.” or “Insights could not analyze this run.”, followed by the cause:
The run says
Fix
The model provider limited the request rate (HTTP 429).
Wait and rerun, or choose a model with more capacity in
Obss AI features
.
The model provider did not find the model (HTTP 404).
Choose another model in
Obss AI features
, then rerun.
The model provider account has no credits (HTTP 402).
Add credits to that account, then rerun.
The model provider refused the credentials (HTTP 401 or 403).
Update the provider connection, then rerun.
To rerun, select
Rerun evals
or
Rerun Insights
on the experiment, as described in
Run Evals again
.
Evals or Insights say the model declined to review a run
The run says “The model declined to review this run.” Models can refuse runs on security topics, such as an agent searching for API keys, and Obss doesn’t retry with the same model.
Under
Obss AI features
, choose another
Evals model
,
Insights model
, or
Experiment insights model
.
Select
Rerun evals
or
Rerun Insights
on the experiment.
The CLI and the plugin return the same message in the run’s
error
.
Evals or Insights did not read the whole run
The recorded work didn’t fit the model’s context window, and a note on
Evals
or
Traces
says the model didn’t read every step or changed file. Traces over 32 MB aren’t saved, and the note says so.
If Evals or Insights fails because the work doesn’t fit, the message names the model. Choose an
Evals model
,
Insights model
, or
Experiment insights model
with a larger context window under
Obss AI features
, then run it again. Learn more in
What Evals read
and
What Insights read
.
Agent mode is not available
Agent mode
for Evals and Insights is in private beta. Email
support@obss.app
to enable it for your organization, and say which feature you want it for. Until then,
New experiment
,
Run evals
,
Rerun evals
,
Run insights
, and
Rerun Insights
show no
Mode
choice for that feature. The CLI and the plugin refuse
mode: "agent"
with
agent_mode_unavailable
: “Agent mode isn’t available for your organization. Use Standard mode instead.”
If your organization can no longer use Agent mode for an experiment that used it:
The
Rerun evals
dialog says “This experiment used Agent mode, which your organization can’t use now. These Evals use Standard mode.”
Rerun Insights
says the same about Insights. The new attempt uses Standard mode.
obss evals preview
and
obss insights preview
say “This experiment launched in Agent mode, which your organization can’t use now. Add —mode standard to insights trigger.” (or
evals trigger
).
A CLI rerun without
--mode
is refused with “This experiment launched Insights in Agent mode, which your organization can’t use now. Rerun with —mode standard.” (or “launched Evals”). Add
--mode standard
. From the plugin, the message says
mode: "standard"
, so add that.
A
schedule
that launches the experiment again in Agent mode pauses. See
A schedule is paused or skips launches
.
Agent mode cannot use the model
Agent mode needs models that can call tools and have a known context window: the
Evals model
for Evals, and both the
Insights model
and the
Experiment insights model
for Insights. Obss checks the models before it launches or reruns, and nothing starts until every model can run Agent mode. The dashboard, the CLI, and the plugin show the same sentence, with the code
agent_mode_model_unsupported
. The sentence names the model that can’t run Agent mode, for example:
“Agent mode can’t use Claude Pro / Max models. Choose an Evals model from an API-key provider, or use Standard mode.”
“Agent mode can’t use
model
. It needs an Insights model that can call tools and has a known context window. Choose another Insights model, or use Standard mode.”
Choose another model under
Obss AI features
, or use Standard mode.
Agent mode did not return a result
An Obss agent stopped before it returned its result. The message says what’s missing, then gives the cause and what to do:
For Evals, the run’s
Evals
tab and its CLI and plugin result say “Evals could not evaluate this run, so it has no Pass or Fail.”
For Insights, the run’s result in
obss insights get
and
get_insights_results
says “Insights could not analyze this run.” The dashboard doesn’t show this sentence yet.
When the insights agent couldn’t group the experiment’s frictions, the Insights attempt’s
error
in
obss insights list
,
list_insights
, and
get_insights_results
says “Insights could not group this experiment’s frictions.” Each run’s review still stands.
The cause names the agent and the model, for example “The insights agent’s work outgrew the Insights model’s context window.”
Cause
Fix
The agent stopped before it returned its result.
Rerun, or switch to Standard mode.
The model’s provider limited requests.
Wait, then rerun only the runs that failed. For a grouping failure, rerun Insights.
The agent’s work outgrew the model’s context window.
Rerun with a model that has a larger context window, or switch to Standard mode.
The provider needs the person who started these Evals or Insights to sign in again in
Profile → Integrations
.
That person signs in again, then reruns.
The provider rejected its saved credentials.
Update the provider connection, then rerun.
The provider refused the agent’s request.
Choose another model in
Obss AI features
and rerun, or switch to Standard mode.
The agent stopped because the run or the experiment was cancelled.
Nothing to fix. Rerun if you still need the result.
To rerun only the failed runs, select
Only process the
N
runs that failed last time
in
Rerun evals
or
Rerun Insights
. Other runs keep their saved results. From the CLI, pass the preview’s
failedRunIds
to
obss evals trigger --run-ids
or
obss insights trigger --run-ids
. From the plugin, pass them to
trigger_evals
or
trigger_insights
as
run_ids
. A grouping failure has no failed runs, and a full Insights rerun in Agent mode reviews every run again.
The Frictions list is empty
Most
frictions
come from Insights, so the list fills in as Insights review the runs.
The list says
Fix
Frictions off
, or only runs that failed before the agent answered
Insights were off at launch. Select
Run insights
.
Some runs have frictions that aren’t grouped yet
Wait for Insights. Meanwhile, they show in each run’s
Traces
tab.
Insights haven’t reviewed some runs
Wait while the experiment runs. If the review failed, select
Rerun Insights
.
Some runs stopped on an unexpected error
Launch again
. An Obss error isn’t a friction, so the run page shows it instead.
Nothing, but you chose a
Where to fix
option or a filter
Choose
All
or select
Clear filters
.
Ask Obss
Ask Obss says the connection was lost
Ask Obss lost its connection, for example after your computer slept or your network changed. Select
Reconnect
, or wait for your network to come back. Your chat and its replies are kept.
Ask Obss says the chat has ended
A
chat
ends 30 days after it starts, and then says “This chat has ended. Start a new chat to continue.” You can still read it. Select
Start a new chat
, and your unsent message moves to the new chat. Do the same if the chat says “This chat’s history is no longer available.”
Ask Obss cannot read a GitHub repository
Ask Obss
reads only public GitHub repositories
. If the repository is private, or the name is wrong, GitHub says that it doesn’t exist. If Ask Obss shows
Sign in with GitHub
, sign in to connect GitHub.
CLI
The CLI does not accept an API key
The key isn’t a personal key, or it was revoked.
Check that
OBSS_API_KEY
holds a personal key from
Profile → API keys
. Organization API keys can’t use the CLI.
If you revoked the key, create a new one.
To use your browser sign-in instead, unset
OBSS_API_KEY
and run
obss login
.
Learn more in
Use an API key
.
The CLI says this version cannot run this command
The installed release is older than the releases that Obss accepts. The command exits with code
4
(
client_update_required
with
--output json
) and prints:
obss: This obss release is older than the server supports: run `obss upgrade`, then retry.
Run
obss upgrade
, then run the command again.
obss upgrade
,
obss version
, and
obss schema
still work because they don’t contact Obss. If
obss upgrade
can’t write the binary, install the CLI again, as described in
When Obss refuses an old release
.
The CLI inside a run doesn’t update itself. If a custom agent downloads the CLI, as when you
run Ask Obss as a custom agent
, enter a current
url
and
sha256
in the agent’s settings.
Plugin (MCP)
The Obss Plugin does not install, sign in, or show its tools
Troubleshoot the plugin
has a fix for each problem:
An install command fails
Sign-in does not open or does not finish
Obss tools or skills are missing
The plugin and a direct connection are both set up
Tools and files
GitHub import fails
Obss imports
tools
only from public
github.com
repositories. After an import, use
Check for updates
to refresh it. The
From GitHub
lists show these messages:
Message
Cause and fix
No public repository has this name
It’s private, misspelled, or deleted. Check the
owner/name
.
No public repository matches
Paste the full
owner/name
or URL.
GitHub search is busy
GitHub limits searches, but exact names still work. Paste the full
owner/name
or URL.
This repository is too large to list
Type the path.
No Skill folders to choose from
No
SKILL.md
at this branch, tag, or commit. Import as Files, or choose another repository.
No branch, tag, or commit named …
Check the name, or leave the field empty for the default branch.
No commits in … yet
Push a commit, then import.
GitHub is not available right now
GitHub may be limiting requests. Select the field again to retry.
Each skill needs its own name in SKILL.md
Two selected
skills
share a
name
, and the message names each clash. Rename one, or choose a path that holds only one.
No skill in this selection is named …
or
No skill in this upload is named …
(in
Import new version
)
Choose or upload only this skill’s own folder.
MCP server sign-in fails
Message
Cause and fix
This provider needs its own OAuth app.
The provider doesn’t register Obss by itself. Create an OAuth app with the redirect URI
https://app.obss.app/oauth/mcp/callback
, then paste its
Client ID
and
Client secret
.
The provider says the redirect URI doesn’t match.
Add
https://app.obss.app/oauth/mcp/callback
to the OAuth app exactly, then connect again.
Sign-in didn’t complete. Check the OAuth app’s Client ID and Client secret, then connect again.
The provider refused the app’s credentials. Many providers require the Client secret.
Learn more in
MCP server sign-in
.
An MCP server’s tools do not show
The server’s
Tools
tab says why it has no list. Obss keeps the last list when a check fails.
Message
Cause and fix
Obss can’t check a local server’s tools outside a run.
It runs inside the task machine, and runs still use it. Type tool names to turn them off.
Obss hasn’t checked this server’s tools yet.
Select
Refresh
.
The last check had no connected account for this server.
Connect your account to the server, then select
Refresh
.
Add the server’s header values to check its tools.
Add the values in the server’s setup, then select
Refresh
.
The server refused the saved credentials.
Check the account or header values, then
Refresh
.
Obss can check only public HTTPS servers.
The address isn’t public HTTPS. Runs can still use the server.
Obss couldn’t reach the server.
Select
Refresh
to try again.
The server didn’t answer as an MCP server.
Check the server’s address.
The server listed more than Obss can keep.
It has over 1,000 tools or is over 4 MB.
If the tab says
Saved values are not bound to this address
, Obss doesn’t check or launch that version until a person selects
Refresh
. The address shows under
Refresh
, in
Binds the saved values to …
. Learn more in
Saved header values and the server address
.
The CLI or the plugin cannot refresh an MCP server’s tools
obss mcp tools refresh
and
Refresh an MCP server’s tools
(
refresh_mcp_server_tools
) fail with
mcp_tool_check_needs_web
when the version’s saved values aren’t bound to its address. Only a person in the dashboard can bind them.
Open the
setupUrl
in the error to go to the version’s
Tools
tab.
Read the address under
Refresh
, in
Binds the saved values to …
.
If you expect it, select
Refresh
to send the values there and bind them. If you don’t, save a new version of the server with the correct address instead.
After that, the CLI and the plugin can refresh the version again.
Sharing
You cannot share an experiment publicly
If the
Share experiment
dialog says “Finish the experiment before you can share it publicly,” wait for the experiment to finish. You can still invite a teammate to view it (
Share results
).
Account
You cannot delete a project
You can’t delete the organization’s only project. Create another
project
first.
You cannot leave the organization
You’re the only member.
Invite someone else
before you
leave
.
Notifications keep arriving in the app after you change your preferences
In-app
is still on for that kind of notification, because email and in-app are separate. Turn off
In-app
for that kind under
Profile → Notifications
.
Account and sign-in
and
Operational alerts
always stay on.
Related
FAQ
Find answers to common questions.
Model providers
Connect and fix the providers that supply models.
Launch an experiment
Launch again after you fix the cause.
CLI reference
Look up each command and its flags.
FAQ
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform