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.

Budget diagnostics

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 attachments per study. A folder selected with Choose folder retains the directory_bundle type and uses one attachment slot; deterministic ZIP is only its transport encoding. Its limits are 512 regular files, 50 MiB total before compression, a 10 MiB payload, 32 path components, and 1,024 UTF-8 path bytes. Unsafe or duplicate paths, multiple roots, unreadable or changing files, and limit overruns are rejected; native Desktop selection also rejects symlinks and special filesystem entries. A browser with directory-entry support accepts mixed dropped files and folders, packaging each top-level folder as one attachment. If the browser cannot read dropped directory entries, use Choose folder.

The Web File API cannot preserve Unix mode bits and writes browser-selected files as ordinary non-executable ZIP entries. That alone does not invalidate a solver folder: the Runtime wrapper ensures the selected solver binary is executable in the isolated workspace. Check that ordinary 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.

Solver folder is not recognized as directory_bundle or solver_bundle

The folder picker must send source_kind=directory; a safe single-root source folder then remains directory_bundle and can carry source_code or a statically supported reference_solver role. A manually uploaded ZIP intentionally remains zip_archive. Backend profiling specializes a safe directory/ZIP to solver_bundle only when it finds both a non-empty README/usage document and an ELF, PE, or Mach-O executable header. It reads at most 64 KiB of README text as untrusted documentation, inspects only bounded binary headers, and neither runs the binary nor extracts the archive as a whole. Unsafe or duplicate paths, symlinks, encrypted members, expansion risk, too many members, or a project-plugin manifest prevent promotion. Clean the folder and upload it again; renaming an arbitrary ZIP does not change its static type.

Provider or model failure

AUTONOMOUS_PLANNER_UNAVAILABLE or AUTONOMOUS_PLAN_NEEDS_CLARIFICATION

The normal Desktop one-request flow requires a connected Scientific Reasoner to produce a strict intent draft before any plugin is installed/enabled or any Run is created. Check Settings → Providers, test the scientific-reasoning route, and then retry. AUTONOMOUS_PLANNER_UNAVAILABLE means the route was missing, failed, or could not return a valid structured draft. AUTONOMOUS_PLAN_NEEDS_CLARIFICATION means the draft was low-confidence or identified a question that would materially change the contract. Desktop presents the question as an AWAITING INPUT item in the Planning Control Room timeline. Add the missing objective, inputs, target variable, threshold, or deliverable there, or explicitly continue with reasonable defaults.

Both outcomes remain preflight states: selected plugins remain unchanged, no Research Run or input artifacts are created, and staged attachments remain available. The Planning Control Room itself is a pre-run UI session, not a partially configured Research Run. Desktop deliberately does not replace the LLM plan with keyword rules.

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. If max_output_tokens was set explicitly, adjust it or the 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.

Solver adapter is not published

Static solver_bundle recognition is not publication permission. Check Allow reusable plugin publishing on the Create page. The contract then requires a file-solver-adapter-v1 source and a passing Local Executor validation record. The fixed publisher accepts exactly three immutable sources—solver_bundle, adapter_source, and validation—and verifies the declared pass state, interface, exact source hashes, and Artifact provenance before Control revalidates the package for managed install and enablement.

The default reviewer status, permissive_deferred, permits publication but records that no independent malware, signature, provenance-authentication, or binary-safety review occurred. It is not a security approval. Validation records and digest attestations establish declared state, identity, and lineage; they are not independent proof that a smoke test ran or that the binary is safe.

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.
• MEMORY_ERROR, OOM, or SIGKILL: ordinary Runtime-generated local jobs currently request 8,192 MiB, enforced as a POSIX address-space limit. Reduce sample mini-batches, chunk coordinates or inference, and remove accidental full-field copies rather than changing the scientific model merely to hide an implementation problem.
• 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.

Delivery validation problems

• MINIMAL_EXAMPLE must ...: emit a UTF-8, syntactically valid .py file with real executable invocation code, and declare it as MINIMAL_EXAMPLE. Imports or prose alone do not qualify.
• USAGE_GUIDE must ...: emit UTF-8 text declared as USAGE_GUIDE and explicitly cover input, output, domain, and fallback. The current validator looks for those four English terms.

An invalid delivery file is not committed as an artifact and cannot satisfy a completion gate.

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.

System VPN, proxy, and certificate settings

The Desktop application follows the operating system routing table, DNS configuration, and VPN routes. Desktop Runtime also imports standard proxy variables, native Windows/macOS proxy settings, GNOME proxy settings, Linux desktop Portal/PAC resolution, proxy bypass rules, and the operating system certificate store. HTTP, HTTPS, and SOCKS proxies are supported. Explicit HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, SSL_CERT_FILE, and SSL_CERT_DIR values take precedence.

Network routes change immediately with the operating system. Proxy settings are refreshed before provider requests, so changing the system connection does not require reconfiguring a provider.