Troubleshooting

Start with run state, then recent events, then logs. Those three usually establish whether the problem is in the contract, model, plugin, or storage layer.

Shortest diagnostic path

CLI:

scientific-agent status RUN_ID
scientific-agent status RUN_ID --events

Control API:

curl -sS http://127.0.0.1:8000/api/v1/health | jq
curl -sS http://127.0.0.1:8000/api/v1/diagnostics | jq
curl -sS http://127.0.0.1:8000/api/v1/runs/RUN_ID/state | jq

In Desktop, open Control Room. Check State's current_terminal_failure and Recent failures, then Timeline with the Failures filter, Jobs, and Model calls. Settings → About can open the log location.

Understand run states

Do not infer a hang only from a stationary progress bar. A long solver may have no intermediate metric. Check Job state and whether Timeline or SSE still receives updates.

Research contract cannot be created

acceptance metric has no producer

The selected capabilities do not declare the criterion under metric_outputs.

• Open capability details and copy the actual metric name.
• Check case, dots, and underscores. Names are normalized, but approximate names are not matched.
• Plugin authors must update both plugin.yaml and the Python manifest.
• If a metric requires independent evaluation, add the corresponding trusted evaluator capability.

Duplicate or conflicting criteria

Each metric may appear once in acceptance_criteria, and its first item must exactly equal acceptance. Merge duplicate conditions or retain the stricter one.

Invalid capability constraint

Each rule may contain only mapping-valued when and require. First run the capability example, then add frozen parameters. Nested fields must match actual plugin inputs.

Input upload fails

Desktop permits at most 20 input files per study. Check that files remain readable, Base64 is complete, and artifact types are appropriate. Large datasets are better generated or imported by a controlled plugin from an explicit location than embedded in an API request.

Provider or model failure

Credential not found

auth_env names an environment variable; it is not the key value:

export OPENAI_API_KEY="..."
python -c 'import os; print(bool(os.environ.get("OPENAI_API_KEY")))'

A different shell, systemd unit, or IDE may not inherit the variable. In Desktop, save the credential again under Settings → Providers and use Test connection.

Codex CLI is not logged in

codex login

Complete browser login and detect it again in Settings. Make sure Desktop and the terminal run as the same operating-system user with the same Codex configuration directory.

Connection works but structured output fails

• Match API format to the endpoint: Responses, Chat Completions, and Anthropic Messages are not interchangeable.
• For a compatible endpoint, select a mode it truly supports: json_schema, json_object, or tool_call.
• Anthropic Messages does not support the json_object mode here.
• Schema repair handles bounded format drift; it cannot repair an incompatible API.

Timeout or repeated retries

Inspect Model calls for latency, failure code, retry count, and fallback. Reduce max_output_tokens or task size before cautiously increasing timeout_seconds. Persistent 401/403, model-not-found, and quota errors do not improve with retries.

Plugin problems

Installed but capability is unavailable

The plugin has not been Enabled, or enabling found missing dependencies. Inspect status, missing_dependencies, and load_error in plugin details.

entrypoint cannot be imported

An entry point uses package.module:ClassName, not a file path. Confirm that:

• the ZIP/directory contains that Python package;
• the package directory has __init__.py;
• the class inherits ScientificPlugin;
• dependencies are installed in the Python environment actually used by Scientific Agent;
• import does not depend on external files or network side effects.

ZIP is rejected

Common causes are several plugin.yaml files, a packaged virtual environment or symlink, path traversal, encrypted entries, or exceeding 10 MiB/50 MiB/512-file limits. Package only the manifest, source, and small required resources.

Capability input is rejected

Copy the capability's example, then replace one field at a time. Ordinary inputs cannot contain undeclared keys. Required artifacts belong under artifact_inputs; do not pass an artifact ID as a normal path field.

Local Executor problems

• Command not found: the required tool is absent from the app process's PATH. Check with the same user and environment in a terminal.
• Output missing: generated code did not write the relative file name declared in JobSpec.
• Nonzero exit: inspect stored stdout, stderr, and structured failure type under Jobs.
• Slow cancellation: an external process is not handling termination promptly; wait for state reconciliation and clean up only inside an isolated environment if necessary.
• Path rejected: inputs and outputs must stay in the workspace; absolute paths and .. are invalid.

Do not fix a task by weakening path checks. Correct its JobSpec or file convention.

Artifact or lineage problems

hash mismatch / corrupt artifact

The underlying file no longer matches its recorded SHA-256. Do not rewrite the record or recalculate the hash to hide it.

1. Stop the run.
2. Preserve logs and a copy of the damaged file.
3. Restore the whole related run from a verified backup, or recompute in a new run.
4. Investigate sync software, manual edits, and disk errors.

Expected lineage edge is missing

A plugin must establish relationships through artifact inputs, existing artifact IDs, or parent_names among artifacts returned together. Mentioning a file name only in free-text metadata does not create an edge.

File cannot be previewed

Control Room previews text and CSV. Large or binary artifacts may be download-only. Open them in a domain tool and compare type, size, and hash shown in the UI.

Storage and recovery problems

Old run cannot be found

The most common cause is a different --data-dir:

scientific-agent --data-dir EXPECTED_DIR status RUN_ID

Check the current directory under Desktop Settings → Storage. Do not confuse the cache root with the data root.

Data directory is read-only or full

Check permissions, mount state, and free space. Pause runs and create a backup before migrating through Settings or /storage/location. Never manually move half the directory while the app is running.

resume is rejected

Only continuable states can resume. SUCCESS, FAILED, and CANCELLED are terminal. Use Recover for INTERRUPTED. For BUDGET_EXHAUSTED, review the run and apply a controlled finite budget increase first.

Control API problems

Call /api/v1/health first to confirm port and mode. The development service exposes its interactive schema at /api/v1/docs. Reconnect SSE with the last cursor; do not open many streams that all replay from after=0.

Benchmark problems

• --prepare-only fails: verify Xsuite/ML dependencies and the spec's relative base_config path.
• Spec hash mismatch: a frozen spec, base config, or protocol-relevant file changed; do not force reuse of the old result root.
• No valid success: inspect each trial's Runtime state and trusted criterion, not only aggregate output.
• Integrity failure: the report is invalid; investigate private-data leakage, event freezing, predictor hashes, and cross-run isolation.
• A rerun did not start over: the difficulty runner resumes by slot by design; use a new --data-dir for an independent experiment.

Update check is unavailable

About displays current Desktop and Runtime versions. If the distribution has no update source configured, Check for updates explicitly reports that it is unavailable; this is not a network failure. Install through the project's official release channel and create a backup before upgrading.

What to include in a bug report

Provide minimal, redacted evidence:

• Desktop, Runtime, operating-system, and Python versions;
• run ID and final status;
• diagnostics output;
• relevant Timeline event types and error codes;
• plugin ID/version, capability ID, and load_error;
• a minimal reproducing config with credentials, private data, and personal absolute paths removed.

Never send API keys, operating-system credentials, evaluator-private content, or an entire sensitive data directory.